@theihtisham/dev-pulse 1.0.0 → 1.1.0

package/devpulse/core/analytics.py

@@ -1,487 +1,487 @@
-"""Analytics engine — computes metrics, insights, and predictions."""
-
-import math
-from datetime import datetime, timedelta, date
-from typing import Any, Optional
-from collections import defaultdict
-
-from devpulse.core.database import Database
-from devpulse.core.models import (
-    DeveloperMetrics,
-    TeamHealth,
-    SprintData,
-    CodeQuality,
-)
-
-
-def _parse_date(dt_str: str) -> Optional[datetime]:
-    """Parse an ISO date string safely."""
-    if not dt_str:
-        return None
-    for fmt in ("%Y-%m-%dT%H:%M:%SZ", "%Y-%m-%dT%H:%M:%S", "%Y-%m-%d"):
-        try:
-            return datetime.strptime(dt_str[:19] if "T" in dt_str else dt_str, fmt)
-        except ValueError:
-            continue
-    return None
-
-
-def _days_between(start: str, end: str) -> float:
-    """Return hours between two ISO date strings."""
-    s = _parse_date(start)
-    e = _parse_date(end)
-    if not s or not e:
-        return 0.0
-    return (e - s).total_seconds() / 3600.0
-
-
-class AnalyticsEngine:
-    """Compute developer metrics, team health, and AI-powered insights."""
-
-    def __init__(self, db: Optional[Database] = None) -> None:
-        self.db = db or Database()
-
-    # ── Developer Metrics ────────────────────────────────────────────
-
-    def developer_metrics(
-        self,
-        author: str,
-        days: int = 30,
-        repo: Optional[str] = None,
-    ) -> DeveloperMetrics:
-        """Compute comprehensive metrics for a single developer."""
-        since = (datetime.utcnow() - timedelta(days=days)).isoformat()
-
-        commits = self.db.get_commits(repo=repo, author=author, since=since)
-        prs = self.db.get_pull_requests(repo=repo, author=author, since=since)
-        issues_raw = self.db.get_issues(repo=repo, since=since)
-        reviews = self.db.get_reviews(author=author, since=since, repo=repo)
-
-        # Filter issues authored by this person
-        issues_opened = [i for i in issues_raw if i.get("author") == author]
-        issues_closed = [i for i in issues_raw if i.get("author") == author and i.get("state") == "closed"]
-
-        # Compute active days
-        commit_dates: set[str] = set()
-        for c in commits:
-            dt = _parse_date(c.get("author_date", ""))
-            if dt:
-                commit_dates.add(dt.strftime("%Y-%m-%d"))
-
-        # Compute avg PR merge time
-        merge_times: list[float] = []
-        prs_merged = 0
-        for p in prs:
-            if p.get("merged_at") and p.get("created_at"):
-                merge_times.append(_days_between(p["created_at"], p["merged_at"]))
-                prs_merged += 1
-        avg_merge_time = sum(merge_times) / len(merge_times) if merge_times else 0.0
-
-        # Compute avg review turnaround
-        review_times: list[float] = []
-        all_prs = self.db.get_pull_requests(repo=repo, since=since)
-        for p in all_prs:
-            pr_reviews = self.db.get_reviews(repo=p.get("repo", ""), since=since)
-            for r in pr_reviews:
-                if r.get("pr_number") == p.get("number") and p.get("created_at") and r.get("submitted_at"):
-                    review_times.append(_days_between(p["created_at"], r["submitted_at"]))
-        avg_review = sum(review_times) / len(review_times) if review_times else 0.0
-
-        lines_added = sum(c.get("additions", 0) for c in commits)
-        lines_removed = sum(c.get("deletions", 0) for c in commits)
-
-        return DeveloperMetrics(
-            author=author,
-            commits_count=len(commits),
-            prs_created=len(prs),
-            prs_merged=prs_merged,
-            issues_opened=len(issues_opened),
-            issues_closed=len(issues_closed),
-            reviews_given=len(reviews),
-            avg_pr_merge_time_hours=round(avg_merge_time, 1),
-            avg_review_turnaround_hours=round(avg_review, 1),
-            lines_added=lines_added,
-            lines_removed=lines_removed,
-            commits_per_day=round(len(commits) / max(days, 1), 2),
-            active_days=len(commit_dates),
-            period_days=days,
-        )
-
-    def team_metrics(self, days: int = 30, repo: Optional[str] = None) -> list[DeveloperMetrics]:
-        """Compute metrics for all contributors."""
-        since = (datetime.utcnow() - timedelta(days=days)).isoformat()
-        commits = self.db.get_commits(repo=repo, since=since)
-        authors = sorted({c["author"] for c in commits if c.get("author")})
-        return [self.developer_metrics(a, days=days, repo=repo) for a in authors]
-
-    # ── Team Health ──────────────────────────────────────────────────
-
-    def team_health(self, days: int = 30, repo: Optional[str] = None) -> TeamHealth:
-        """Analyze team health: workload balance, burnout risk, collaboration."""
-        metrics = self.team_metrics(days=days, repo=repo)
-        if not metrics:
-            return TeamHealth(overall_score=0, recommendations=["No data available — sync GitHub first."])
-
-        # Workload balance: standard deviation of commits as ratio of mean
-        commit_counts = [m.commits_count for m in metrics]
-        mean_commits = sum(commit_counts) / len(commit_counts)
-        if mean_commits > 0:
-            variance = sum((c - mean_commits) ** 2 for c in commit_counts) / len(commit_counts)
-            std_dev = math.sqrt(variance)
-            balance = max(0.0, 1.0 - (std_dev / mean_commits))
-        else:
-            balance = 1.0
-
-        # Burnout risk per person
-        burnout_risk: dict[str, float] = {}
-        for m in metrics:
-            risk = 0.0
-            if m.period_days > 0:
-                commits_per_day = m.commits_count / m.period_days
-                if commits_per_day > 10:
-                    risk += 0.3
-                if m.active_days > m.period_days * 0.9:
-                    risk += 0.3
-                if m.avg_pr_merge_time_hours > 48:
-                    risk += 0.2
-                if m.commits_per_day > 8:
-                    risk += 0.2
-            burnout_risk[m.author] = round(min(risk, 1.0), 2)
-
-        # Collaboration score: reviews / PRs ratio
-        total_reviews = sum(m.reviews_given for m in metrics)
-        total_prs = sum(m.prs_created for m in metrics)
-        collab = min(total_reviews / max(total_prs, 1), 2.0) / 2.0 if total_prs > 0 else 0.5
-
-        # Velocity trend
-        prev_commits = self.db.get_commits(
-            repo=repo,
-            since=(datetime.utcnow() - timedelta(days=days * 2)).isoformat(),
-            until=(datetime.utcnow() - timedelta(days=days)).isoformat(),
-        )
-        curr_commits = self.db.get_commits(
-            repo=repo, since=(datetime.utcnow() - timedelta(days=days)).isoformat()
-        )
-        prev_count = len(prev_commits)
-        curr_count = len(curr_commits)
-        if prev_count == 0:
-            trend = "growing"
-        elif curr_count > prev_count * 1.1:
-            trend = "growing"
-        elif curr_count < prev_count * 0.9:
-            trend = "declining"
-        else:
-            trend = "stable"
-
-        # Overall score
-        overall = round((balance * 0.3 + collab * 0.3 + (1.0 - max(burnout_risk.values())) * 0.4) * 100, 1)
-
-        # Recommendations
-        recs: list[str] = []
-        high_burnout = [name for name, risk in burnout_risk.items() if risk >= 0.6]
-        if high_burnout:
-            recs.append(f"High burnout risk for: {', '.join(high_burnout)}. Consider redistributing workload.")
-        if balance < 0.5:
-            recs.append("Workload is heavily imbalanced. Review task assignment practices.")
-        if collab < 0.3:
-            recs.append("Low code review participation. Encourage team members to review more PRs.")
-        if trend == "declining":
-            recs.append("Commit velocity is declining. Check for blockers or team morale issues.")
-        if not recs:
-            recs.append("Team health looks good! Keep up the great work.")
-
-        return TeamHealth(
-            overall_score=overall,
-            workload_balance=round(balance, 2),
-            burnout_risk=burnout_risk,
-            collaboration_score=round(collab, 2),
-            velocity_trend=trend,
-            recommendations=recs,
-        )
-
-    # ── Sprint Analytics ─────────────────────────────────────────────
-
-    def sprint_analytics(self, sprint_name: Optional[str] = None) -> list[SprintData]:
-        """Compute sprint velocity and burndown data."""
-        if sprint_name:
-            snapshots = self.db.get_sprint_snapshots(sprint_name)
-            if not snapshots:
-                return []
-            s = snapshots[-1]
-            total = s["total_points"]
-            completed = s["completed_points"]
-            added = s.get("added_points", 0)
-            return [
-                SprintData(
-                    name=sprint_name,
-                    total_points=total,
-                    completed_points=completed,
-                    remaining_points=total - completed,
-                    added_points=added,
-                    velocity=round(completed, 1),
-                    scope_creep_pct=round(added / max(total - added, 1) * 100, 1),
-                )
-            ]
-
-        # Return data for all sprints
-        conn = self.db._connect()
-        try:
-            sprints = conn.execute(
-                "SELECT DISTINCT sprint_name FROM sprint_snapshots ORDER BY sprint_name"
-            ).fetchall()
-        finally:
-            conn.close()
-
-        results: list[SprintData] = []
-        for sp in sprints:
-            results.extend(self.sprint_analytics(sp["sprint_name"]))
-        return results
-
-    def sprint_burndown(self, sprint_name: str) -> list[dict[str, Any]]:
-        """Get burndown data points for ASCII chart."""
-        snapshots = self.db.get_sprint_snapshots(sprint_name)
-        if not snapshots:
-            return []
-        return [
-            {
-                "day": i + 1,
-                "remaining": s["remaining_points"],
-                "ideal": snapshots[0]["remaining_points"] * (1 - (i / max(len(snapshots) - 1, 1))),
-            }
-            for i, s in enumerate(snapshots)
-        ]
-
-    def predict_sprint_completion(
-        self, sprint_name: str, total_points: float, days_elapsed: int, total_days: int
-    ) -> dict[str, Any]:
-        """Predict if sprint will complete on time."""
-        snapshots = self.db.get_sprint_snapshots(sprint_name)
-        if not snapshots:
-            return {"prediction": "unknown", "confidence": 0, "message": "No data"}
-
-        completed = snapshots[-1]["completed_points"]
-        velocity = completed / max(days_elapsed, 1)
-        remaining = total_points - completed
-        days_left = total_days - days_elapsed
-        predicted_completion = velocity * days_left if velocity > 0 else 0
-
-        if predicted_completion >= remaining:
-            pct = round((predicted_completion - remaining) / max(remaining, 1) * 100, 1)
-            return {
-                "prediction": "on_track",
-                "confidence": min(pct, 100),
-                "message": f"On track — {pct}% buffer remaining. Predicted velocity: {velocity:.1f} pts/day.",
-            }
-        else:
-            deficit = round(remaining - predicted_completion, 1)
-            return {
-                "prediction": "at_risk",
-                "confidence": round((1 - predicted_completion / max(remaining, 1)) * 100, 1),
-                "message": f"At risk — {deficit} points may not be completed. Consider reducing scope.",
-            }
-
-    # ── Code Quality ─────────────────────────────────────────────────
-
-    def code_quality_trend(self, repo: Optional[str] = None, days: int = 90) -> list[CodeQuality]:
-        """Get code quality snapshots over time."""
-        rows = self.db.get_quality_snapshots(repo=repo, days=days)
-        return [
-            CodeQuality(
-                repo=r["repo"],
-                date=r["snapshot_date"],
-                test_coverage=r.get("test_coverage", 0),
-                open_bugs=r.get("open_bugs", 0),
-                tech_debt_score=r.get("tech_debt_score", 0),
-                lines_added=r.get("lines_added", 0),
-                lines_removed=r.get("lines_removed", 0),
-                files_changed=r.get("files_changed", 0),
-            )
-            for r in rows
-        ]
-
-    def compute_quality_score(self, repo: str, days: int = 30) -> dict[str, Any]:
-        """Compute aggregate code quality score from commit/PR data."""
-        since = (datetime.utcnow() - timedelta(days=days)).isoformat()
-        commits = self.db.get_commits(repo=repo, since=since)
-        prs = self.db.get_pull_requests(repo=repo, since=since)
-        issues = self.db.get_issues(repo=repo, since=since)
-
-        total_additions = sum(c.get("additions", 0) for c in commits)
-        total_deletions = sum(c.get("deletions", 0) for c in commits)
-        bug_issues = [i for i in issues if "bug" in " ".join(
-            i.get("labels", []) if isinstance(i.get("labels"), list) else []
-        ).lower()]
-
-        churn = total_additions + total_deletions
-        # Simple tech debt heuristic: bug rate + PR size
-        avg_pr_size = (total_additions + total_deletions) / max(len(prs), 1)
-        bug_rate = len(bug_issues) / max(len(commits), 1)
-        tech_debt = min(10, round(bug_rate * 50 + avg_pr_size / 100, 1))
-
-        return {
-            "repo": repo,
-            "churn": churn,
-            "bug_count": len(bug_issues),
-            "bug_rate": round(bug_rate, 3),
-            "avg_pr_size": round(avg_pr_size, 0),
-            "tech_debt_score": tech_debt,
-            "total_commits": len(commits),
-            "total_prs": len(prs),
-        }
-
-    # ── AI Insights ──────────────────────────────────────────────────
-
-    def generate_insights(self, days: int = 30, repo: Optional[str] = None) -> list[dict[str, str]]:
-        """Generate AI-powered insights and recommendations."""
-        insights: list[dict[str, str]] = []
-        since = (datetime.utcnow() - timedelta(days=days)).isoformat()
-
-        commits = self.db.get_commits(repo=repo, since=since)
-        prs = self.db.get_pull_requests(repo=repo, since=since)
-        issues = self.db.get_issues(repo=repo, since=since)
-
-        # Insight: PR merge time
-        merge_times: list[float] = []
-        for p in prs:
-            if p.get("merged_at") and p.get("created_at"):
-                h = _days_between(p["created_at"], p["merged_at"])
-                merge_times.append(h)
-        if merge_times:
-            avg_mt = sum(merge_times) / len(merge_times)
-            if avg_mt > 48:
-                insights.append({
-                    "type": "bottleneck",
-                    "severity": "high",
-                    "message": f"Average PR merge time is {avg_mt:.0f}h (>48h). Reviews are a bottleneck.",
-                    "recommendation": "Consider assigning dedicated reviewers or setting SLA for reviews.",
-                })
-            elif avg_mt > 24:
-                insights.append({
-                    "type": "warning",
-                    "severity": "medium",
-                    "message": f"Average PR merge time is {avg_mt:.0f}h. Room for improvement.",
-                    "recommendation": "Set up PR size guidelines and automated review reminders.",
-                })
-            else:
-                insights.append({
-                    "type": "positive",
-                    "severity": "low",
-                    "message": f"PR merge time is healthy at {avg_mt:.0f}h.",
-                    "recommendation": "Maintain current review practices.",
-                })
-
-        # Insight: Issue velocity
-        closed_issues = [i for i in issues if i.get("state") == "closed"]
-        open_issues = [i for i in issues if i.get("state") == "open"]
-        if open_issues and closed_issues:
-            close_rate = len(closed_issues) / max(days, 1)
-            days_to_clear = len(open_issues) / max(close_rate, 0.01)
-            if days_to_clear > 60:
-                insights.append({
-                    "type": "bottleneck",
-                    "severity": "high",
-                    "message": f"Open backlog would take {days_to_clear:.0f} days to clear at current rate.",
-                    "recommendation": "Prioritize issue triage. Consider closing stale issues.",
-                })
-
-        # Insight: Commit patterns
-        author_commits: dict[str, int] = defaultdict(int)
-        for c in commits:
-            author_commits[c.get("author", "unknown")] += 1
-        if author_commits:
-            max_author = max(author_commits, key=author_commits.get)  # type: ignore[arg-type]
-            max_count = author_commits[max_author]
-            total = sum(author_commits.values())
-            if max_count > total * 0.5 and len(author_commits) > 1:
-                insights.append({
-                    "type": "warning",
-                    "severity": "medium",
-                    "message": f"{max_author} authored {max_count}/{total} commits ({max_count*100//total}%). Bus factor risk.",
-                    "recommendation": "Encourage knowledge sharing and pair programming.",
-                })
-
-        # Insight: Large PRs
-        large_prs = [p for p in prs if p.get("additions", 0) + p.get("deletions", 0) > 500]
-        if large_prs:
-            insights.append({
-                "type": "warning",
-                "severity": "medium",
-                "message": f"{len(large_prs)} PRs with 500+ lines changed. These are harder to review.",
-                "recommendation": "Break large changes into smaller, focused PRs for faster reviews.",
-            })
-
-        # Insight: Weekend work
-        weekend_commits = 0
-        for c in commits:
-            dt = _parse_date(c.get("author_date", ""))
-            if dt and dt.weekday() >= 5:
-                weekend_commits += 1
-        if weekend_commits > len(commits) * 0.15 and weekend_commits > 3:
-            insights.append({
-                "type": "warning",
-                "severity": "medium",
-                "message": f"{weekend_commits} commits ({weekend_commits*100//max(len(commits),1)}%) on weekends.",
-                "recommendation": "Check for sustainable pace. Persistent weekend work signals potential burnout.",
-            })
-
-        if not insights:
-            insights.append({
-                "type": "positive",
-                "severity": "low",
-                "message": "No significant issues detected. Team is performing well.",
-                "recommendation": "Keep monitoring metrics and maintain current practices.",
-            })
-
-        return insights
-
-    # ── Activity Heatmap ─────────────────────────────────────────────
-
-    def activity_heatmap(self, author: Optional[str] = None, days: int = 365) -> list[dict[str, Any]]:
-        """Get daily commit counts for contribution heatmap."""
-        return self.db.get_commit_count_by_day(author=author, days=days)
-
-    # ── Goal Progress ────────────────────────────────────────────────
-
-    def goal_coaching(self, goal_id: Optional[int] = None) -> list[dict[str, Any]]:
-        """Generate AI coaching for goals."""
-        if goal_id:
-            goals = [g for g in self.db.get_goals() if g["id"] == goal_id]
-        else:
-            goals = self.db.get_goals(status="active")
-
-        coaching: list[dict[str, Any]] = []
-        for g in goals:
-            target = g["target_value"]
-            current = g["current_value"]
-            pct = (current / target * 100) if target > 0 else 0
-            remaining = target - current
-
-            advice = ""
-            if pct >= 100:
-                advice = "Goal achieved! Consider setting a new stretch target."
-                status = "achieved"
-            elif pct >= 75:
-                advice = "Almost there! Push through the final stretch."
-                status = "on_track"
-            elif pct >= 50:
-                advice = "Good progress. Maintain momentum and check for blockers."
-                status = "on_track"
-            elif pct >= 25:
-                advice = "Behind pace. Identify what's blocking progress and address it."
-                status = "at_risk"
-            else:
-                advice = "Significantly behind. Consider adjusting the target or removing obstacles."
-                status = "at_risk"
-
-            coaching.append({
-                "goal": g["title"],
-                "metric": g["metric"],
-                "progress_pct": round(pct, 1),
-                "current": current,
-                "target": target,
-                "remaining": round(remaining, 1),
-                "status": status,
-                "advice": advice,
-            })
-
-        return coaching
+"""Analytics engine — computes metrics, insights, and predictions."""
+
+import math
+from datetime import datetime, timedelta, date
+from typing import Any, Optional
+from collections import defaultdict
+
+from devpulse.core.database import Database
+from devpulse.core.models import (
+    DeveloperMetrics,
+    TeamHealth,
+    SprintData,
+    CodeQuality,
+)
+
+
+def _parse_date(dt_str: str) -> Optional[datetime]:
+    """Parse an ISO date string safely."""
+    if not dt_str:
+        return None
+    for fmt in ("%Y-%m-%dT%H:%M:%SZ", "%Y-%m-%dT%H:%M:%S", "%Y-%m-%d"):
+        try:
+            return datetime.strptime(dt_str[:19] if "T" in dt_str else dt_str, fmt)
+        except ValueError:
+            continue
+    return None
+
+
+def _days_between(start: str, end: str) -> float:
+    """Return hours between two ISO date strings."""
+    s = _parse_date(start)
+    e = _parse_date(end)
+    if not s or not e:
+        return 0.0
+    return (e - s).total_seconds() / 3600.0
+
+
+class AnalyticsEngine:
+    """Compute developer metrics, team health, and AI-powered insights."""
+
+    def __init__(self, db: Optional[Database] = None) -> None:
+        self.db = db or Database()
+
+    # ── Developer Metrics ────────────────────────────────────────────
+
+    def developer_metrics(
+        self,
+        author: str,
+        days: int = 30,
+        repo: Optional[str] = None,
+    ) -> DeveloperMetrics:
+        """Compute comprehensive metrics for a single developer."""
+        since = (datetime.utcnow() - timedelta(days=days)).isoformat()
+
+        commits = self.db.get_commits(repo=repo, author=author, since=since)
+        prs = self.db.get_pull_requests(repo=repo, author=author, since=since)
+        issues_raw = self.db.get_issues(repo=repo, since=since)
+        reviews = self.db.get_reviews(author=author, since=since, repo=repo)
+
+        # Filter issues authored by this person
+        issues_opened = [i for i in issues_raw if i.get("author") == author]
+        issues_closed = [i for i in issues_raw if i.get("author") == author and i.get("state") == "closed"]
+
+        # Compute active days
+        commit_dates: set[str] = set()
+        for c in commits:
+            dt = _parse_date(c.get("author_date", ""))
+            if dt:
+                commit_dates.add(dt.strftime("%Y-%m-%d"))
+
+        # Compute avg PR merge time
+        merge_times: list[float] = []
+        prs_merged = 0
+        for p in prs:
+            if p.get("merged_at") and p.get("created_at"):
+                merge_times.append(_days_between(p["created_at"], p["merged_at"]))
+                prs_merged += 1
+        avg_merge_time = sum(merge_times) / len(merge_times) if merge_times else 0.0
+
+        # Compute avg review turnaround
+        review_times: list[float] = []
+        all_prs = self.db.get_pull_requests(repo=repo, since=since)
+        for p in all_prs:
+            pr_reviews = self.db.get_reviews(repo=p.get("repo", ""), since=since)
+            for r in pr_reviews:
+                if r.get("pr_number") == p.get("number") and p.get("created_at") and r.get("submitted_at"):
+                    review_times.append(_days_between(p["created_at"], r["submitted_at"]))
+        avg_review = sum(review_times) / len(review_times) if review_times else 0.0
+
+        lines_added = sum(c.get("additions", 0) for c in commits)
+        lines_removed = sum(c.get("deletions", 0) for c in commits)
+
+        return DeveloperMetrics(
+            author=author,
+            commits_count=len(commits),
+            prs_created=len(prs),
+            prs_merged=prs_merged,
+            issues_opened=len(issues_opened),
+            issues_closed=len(issues_closed),
+            reviews_given=len(reviews),
+            avg_pr_merge_time_hours=round(avg_merge_time, 1),
+            avg_review_turnaround_hours=round(avg_review, 1),
+            lines_added=lines_added,
+            lines_removed=lines_removed,
+            commits_per_day=round(len(commits) / max(days, 1), 2),
+            active_days=len(commit_dates),
+            period_days=days,
+        )
+
+    def team_metrics(self, days: int = 30, repo: Optional[str] = None) -> list[DeveloperMetrics]:
+        """Compute metrics for all contributors."""
+        since = (datetime.utcnow() - timedelta(days=days)).isoformat()
+        commits = self.db.get_commits(repo=repo, since=since)
+        authors = sorted({c["author"] for c in commits if c.get("author")})
+        return [self.developer_metrics(a, days=days, repo=repo) for a in authors]
+
+    # ── Team Health ──────────────────────────────────────────────────
+
+    def team_health(self, days: int = 30, repo: Optional[str] = None) -> TeamHealth:
+        """Analyze team health: workload balance, burnout risk, collaboration."""
+        metrics = self.team_metrics(days=days, repo=repo)
+        if not metrics:
+            return TeamHealth(overall_score=0, recommendations=["No data available — sync GitHub first."])
+
+        # Workload balance: standard deviation of commits as ratio of mean
+        commit_counts = [m.commits_count for m in metrics]
+        mean_commits = sum(commit_counts) / len(commit_counts)
+        if mean_commits > 0:
+            variance = sum((c - mean_commits) ** 2 for c in commit_counts) / len(commit_counts)
+            std_dev = math.sqrt(variance)
+            balance = max(0.0, 1.0 - (std_dev / mean_commits))
+        else:
+            balance = 1.0
+
+        # Burnout risk per person
+        burnout_risk: dict[str, float] = {}
+        for m in metrics:
+            risk = 0.0
+            if m.period_days > 0:
+                commits_per_day = m.commits_count / m.period_days
+                if commits_per_day > 10:
+                    risk += 0.3
+                if m.active_days > m.period_days * 0.9:
+                    risk += 0.3
+                if m.avg_pr_merge_time_hours > 48:
+                    risk += 0.2
+                if m.commits_per_day > 8:
+                    risk += 0.2
+            burnout_risk[m.author] = round(min(risk, 1.0), 2)
+
+        # Collaboration score: reviews / PRs ratio
+        total_reviews = sum(m.reviews_given for m in metrics)
+        total_prs = sum(m.prs_created for m in metrics)
+        collab = min(total_reviews / max(total_prs, 1), 2.0) / 2.0 if total_prs > 0 else 0.5
+
+        # Velocity trend
+        prev_commits = self.db.get_commits(
+            repo=repo,
+            since=(datetime.utcnow() - timedelta(days=days * 2)).isoformat(),
+            until=(datetime.utcnow() - timedelta(days=days)).isoformat(),
+        )
+        curr_commits = self.db.get_commits(
+            repo=repo, since=(datetime.utcnow() - timedelta(days=days)).isoformat()
+        )
+        prev_count = len(prev_commits)
+        curr_count = len(curr_commits)
+        if prev_count == 0:
+            trend = "growing"
+        elif curr_count > prev_count * 1.1:
+            trend = "growing"
+        elif curr_count < prev_count * 0.9:
+            trend = "declining"
+        else:
+            trend = "stable"
+
+        # Overall score
+        overall = round((balance * 0.3 + collab * 0.3 + (1.0 - max(burnout_risk.values())) * 0.4) * 100, 1)
+
+        # Recommendations
+        recs: list[str] = []
+        high_burnout = [name for name, risk in burnout_risk.items() if risk >= 0.6]
+        if high_burnout:
+            recs.append(f"High burnout risk for: {', '.join(high_burnout)}. Consider redistributing workload.")
+        if balance < 0.5:
+            recs.append("Workload is heavily imbalanced. Review task assignment practices.")
+        if collab < 0.3:
+            recs.append("Low code review participation. Encourage team members to review more PRs.")
+        if trend == "declining":
+            recs.append("Commit velocity is declining. Check for blockers or team morale issues.")
+        if not recs:
+            recs.append("Team health looks good! Keep up the great work.")
+
+        return TeamHealth(
+            overall_score=overall,
+            workload_balance=round(balance, 2),
+            burnout_risk=burnout_risk,
+            collaboration_score=round(collab, 2),
+            velocity_trend=trend,
+            recommendations=recs,
+        )
+
+    # ── Sprint Analytics ─────────────────────────────────────────────
+
+    def sprint_analytics(self, sprint_name: Optional[str] = None) -> list[SprintData]:
+        """Compute sprint velocity and burndown data."""
+        if sprint_name:
+            snapshots = self.db.get_sprint_snapshots(sprint_name)
+            if not snapshots:
+                return []
+            s = snapshots[-1]
+            total = s["total_points"]
+            completed = s["completed_points"]
+            added = s.get("added_points", 0)
+            return [
+                SprintData(
+                    name=sprint_name,
+                    total_points=total,
+                    completed_points=completed,
+                    remaining_points=total - completed,
+                    added_points=added,
+                    velocity=round(completed, 1),
+                    scope_creep_pct=round(added / max(total - added, 1) * 100, 1),
+                )
+            ]
+
+        # Return data for all sprints
+        conn = self.db._connect()
+        try:
+            sprints = conn.execute(
+                "SELECT DISTINCT sprint_name FROM sprint_snapshots ORDER BY sprint_name"
+            ).fetchall()
+        finally:
+            conn.close()
+
+        results: list[SprintData] = []
+        for sp in sprints:
+            results.extend(self.sprint_analytics(sp["sprint_name"]))
+        return results
+
+    def sprint_burndown(self, sprint_name: str) -> list[dict[str, Any]]:
+        """Get burndown data points for ASCII chart."""
+        snapshots = self.db.get_sprint_snapshots(sprint_name)
+        if not snapshots:
+            return []
+        return [
+            {
+                "day": i + 1,
+                "remaining": s["remaining_points"],
+                "ideal": snapshots[0]["remaining_points"] * (1 - (i / max(len(snapshots) - 1, 1))),
+            }
+            for i, s in enumerate(snapshots)
+        ]
+
+    def predict_sprint_completion(
+        self, sprint_name: str, total_points: float, days_elapsed: int, total_days: int
+    ) -> dict[str, Any]:
+        """Predict if sprint will complete on time."""
+        snapshots = self.db.get_sprint_snapshots(sprint_name)
+        if not snapshots:
+            return {"prediction": "unknown", "confidence": 0, "message": "No data"}
+
+        completed = snapshots[-1]["completed_points"]
+        velocity = completed / max(days_elapsed, 1)
+        remaining = total_points - completed
+        days_left = total_days - days_elapsed
+        predicted_completion = velocity * days_left if velocity > 0 else 0
+
+        if predicted_completion >= remaining:
+            pct = round((predicted_completion - remaining) / max(remaining, 1) * 100, 1)
+            return {
+                "prediction": "on_track",
+                "confidence": min(pct, 100),
+                "message": f"On track — {pct}% buffer remaining. Predicted velocity: {velocity:.1f} pts/day.",
+            }
+        else:
+            deficit = round(remaining - predicted_completion, 1)
+            return {
+                "prediction": "at_risk",
+                "confidence": round((1 - predicted_completion / max(remaining, 1)) * 100, 1),
+                "message": f"At risk — {deficit} points may not be completed. Consider reducing scope.",
+            }
+
+    # ── Code Quality ─────────────────────────────────────────────────
+
+    def code_quality_trend(self, repo: Optional[str] = None, days: int = 90) -> list[CodeQuality]:
+        """Get code quality snapshots over time."""
+        rows = self.db.get_quality_snapshots(repo=repo, days=days)
+        return [
+            CodeQuality(
+                repo=r["repo"],
+                date=r["snapshot_date"],
+                test_coverage=r.get("test_coverage", 0),
+                open_bugs=r.get("open_bugs", 0),
+                tech_debt_score=r.get("tech_debt_score", 0),
+                lines_added=r.get("lines_added", 0),
+                lines_removed=r.get("lines_removed", 0),
+                files_changed=r.get("files_changed", 0),
+            )
+            for r in rows
+        ]
+
+    def compute_quality_score(self, repo: str, days: int = 30) -> dict[str, Any]:
+        """Compute aggregate code quality score from commit/PR data."""
+        since = (datetime.utcnow() - timedelta(days=days)).isoformat()
+        commits = self.db.get_commits(repo=repo, since=since)
+        prs = self.db.get_pull_requests(repo=repo, since=since)
+        issues = self.db.get_issues(repo=repo, since=since)
+
+        total_additions = sum(c.get("additions", 0) for c in commits)
+        total_deletions = sum(c.get("deletions", 0) for c in commits)
+        bug_issues = [i for i in issues if "bug" in " ".join(
+            i.get("labels", []) if isinstance(i.get("labels"), list) else []
+        ).lower()]
+
+        churn = total_additions + total_deletions
+        # Simple tech debt heuristic: bug rate + PR size
+        avg_pr_size = (total_additions + total_deletions) / max(len(prs), 1)
+        bug_rate = len(bug_issues) / max(len(commits), 1)
+        tech_debt = min(10, round(bug_rate * 50 + avg_pr_size / 100, 1))
+
+        return {
+            "repo": repo,
+            "churn": churn,
+            "bug_count": len(bug_issues),
+            "bug_rate": round(bug_rate, 3),
+            "avg_pr_size": round(avg_pr_size, 0),
+            "tech_debt_score": tech_debt,
+            "total_commits": len(commits),
+            "total_prs": len(prs),
+        }
+
+    # ── AI Insights ──────────────────────────────────────────────────
+
+    def generate_insights(self, days: int = 30, repo: Optional[str] = None) -> list[dict[str, str]]:
+        """Generate AI-powered insights and recommendations."""
+        insights: list[dict[str, str]] = []
+        since = (datetime.utcnow() - timedelta(days=days)).isoformat()
+
+        commits = self.db.get_commits(repo=repo, since=since)
+        prs = self.db.get_pull_requests(repo=repo, since=since)
+        issues = self.db.get_issues(repo=repo, since=since)
+
+        # Insight: PR merge time
+        merge_times: list[float] = []
+        for p in prs:
+            if p.get("merged_at") and p.get("created_at"):
+                h = _days_between(p["created_at"], p["merged_at"])
+                merge_times.append(h)
+        if merge_times:
+            avg_mt = sum(merge_times) / len(merge_times)
+            if avg_mt > 48:
+                insights.append({
+                    "type": "bottleneck",
+                    "severity": "high",
+                    "message": f"Average PR merge time is {avg_mt:.0f}h (>48h). Reviews are a bottleneck.",
+                    "recommendation": "Consider assigning dedicated reviewers or setting SLA for reviews.",
+                })
+            elif avg_mt > 24:
+                insights.append({
+                    "type": "warning",
+                    "severity": "medium",
+                    "message": f"Average PR merge time is {avg_mt:.0f}h. Room for improvement.",
+                    "recommendation": "Set up PR size guidelines and automated review reminders.",
+                })
+            else:
+                insights.append({
+                    "type": "positive",
+                    "severity": "low",
+                    "message": f"PR merge time is healthy at {avg_mt:.0f}h.",
+                    "recommendation": "Maintain current review practices.",
+                })
+
+        # Insight: Issue velocity
+        closed_issues = [i for i in issues if i.get("state") == "closed"]
+        open_issues = [i for i in issues if i.get("state") == "open"]
+        if open_issues and closed_issues:
+            close_rate = len(closed_issues) / max(days, 1)
+            days_to_clear = len(open_issues) / max(close_rate, 0.01)
+            if days_to_clear > 60:
+                insights.append({
+                    "type": "bottleneck",
+                    "severity": "high",
+                    "message": f"Open backlog would take {days_to_clear:.0f} days to clear at current rate.",
+                    "recommendation": "Prioritize issue triage. Consider closing stale issues.",
+                })
+
+        # Insight: Commit patterns
+        author_commits: dict[str, int] = defaultdict(int)
+        for c in commits:
+            author_commits[c.get("author", "unknown")] += 1
+        if author_commits:
+            max_author = max(author_commits, key=author_commits.get)  # type: ignore[arg-type]
+            max_count = author_commits[max_author]
+            total = sum(author_commits.values())
+            if max_count > total * 0.5 and len(author_commits) > 1:
+                insights.append({
+                    "type": "warning",
+                    "severity": "medium",
+                    "message": f"{max_author} authored {max_count}/{total} commits ({max_count*100//total}%). Bus factor risk.",
+                    "recommendation": "Encourage knowledge sharing and pair programming.",
+                })
+
+        # Insight: Large PRs
+        large_prs = [p for p in prs if p.get("additions", 0) + p.get("deletions", 0) > 500]
+        if large_prs:
+            insights.append({
+                "type": "warning",
+                "severity": "medium",
+                "message": f"{len(large_prs)} PRs with 500+ lines changed. These are harder to review.",
+                "recommendation": "Break large changes into smaller, focused PRs for faster reviews.",
+            })
+
+        # Insight: Weekend work
+        weekend_commits = 0
+        for c in commits:
+            dt = _parse_date(c.get("author_date", ""))
+            if dt and dt.weekday() >= 5:
+                weekend_commits += 1
+        if weekend_commits > len(commits) * 0.15 and weekend_commits > 3:
+            insights.append({
+                "type": "warning",
+                "severity": "medium",
+                "message": f"{weekend_commits} commits ({weekend_commits*100//max(len(commits),1)}%) on weekends.",
+                "recommendation": "Check for sustainable pace. Persistent weekend work signals potential burnout.",
+            })
+
+        if not insights:
+            insights.append({
+                "type": "positive",
+                "severity": "low",
+                "message": "No significant issues detected. Team is performing well.",
+                "recommendation": "Keep monitoring metrics and maintain current practices.",
+            })
+
+        return insights
+
+    # ── Activity Heatmap ─────────────────────────────────────────────
+
+    def activity_heatmap(self, author: Optional[str] = None, days: int = 365) -> list[dict[str, Any]]:
+        """Get daily commit counts for contribution heatmap."""
+        return self.db.get_commit_count_by_day(author=author, days=days)
+
+    # ── Goal Progress ────────────────────────────────────────────────
+
+    def goal_coaching(self, goal_id: Optional[int] = None) -> list[dict[str, Any]]:
+        """Generate AI coaching for goals."""
+        if goal_id:
+            goals = [g for g in self.db.get_goals() if g["id"] == goal_id]
+        else:
+            goals = self.db.get_goals(status="active")
+
+        coaching: list[dict[str, Any]] = []
+        for g in goals:
+            target = g["target_value"]
+            current = g["current_value"]
+            pct = (current / target * 100) if target > 0 else 0
+            remaining = target - current
+
+            advice = ""
+            if pct >= 100:
+                advice = "Goal achieved! Consider setting a new stretch target."
+                status = "achieved"
+            elif pct >= 75:
+                advice = "Almost there! Push through the final stretch."
+                status = "on_track"
+            elif pct >= 50:
+                advice = "Good progress. Maintain momentum and check for blockers."
+                status = "on_track"
+            elif pct >= 25:
+                advice = "Behind pace. Identify what's blocking progress and address it."
+                status = "at_risk"
+            else:
+                advice = "Significantly behind. Consider adjusting the target or removing obstacles."
+                status = "at_risk"
+
+            coaching.append({
+                "goal": g["title"],
+                "metric": g["metric"],
+                "progress_pct": round(pct, 1),
+                "current": current,
+                "target": target,
+                "remaining": round(remaining, 1),
+                "status": status,
+                "advice": advice,
+            })
+
+        return coaching