@theihtisham/dev-pulse 1.0.0 → 1.1.0

package/devpulse/core/report_generator.py

@@ -1,454 +1,454 @@
-"""Report generator — produces Markdown, JSON, and HTML reports."""
-
-import json
-import os
-from datetime import datetime, timedelta
-from pathlib import Path
-from typing import Any, Optional
-
-from jinja2 import Environment, FileSystemLoader, BaseLoader
-
-from devpulse.core.database import Database
-from devpulse.core.analytics import AnalyticsEngine
-from devpulse.core.config import get_settings
-
-
-class ReportGenerator:
-    """Generate daily, weekly, and monthly reports in multiple formats."""
-
-    def __init__(self, db: Optional[Database] = None) -> None:
-        self.db = db or Database()
-        self.engine = AnalyticsEngine(db=self.db)
-        settings = get_settings()
-        self.reports_dir = settings.reports_dir
-        Path(self.reports_dir).mkdir(parents=True, exist_ok=True)
-
-        # Set up Jinja2 for HTML reports
-        template_dir = Path(__file__).parent.parent / "templates"
-        if template_dir.exists():
-            self.jinja_env = Environment(loader=FileSystemLoader(str(template_dir)))
-        else:
-            self.jinja_env = Environment(loader=BaseLoader())
-
-    # ── Daily Report ─────────────────────────────────────────────────
-
-    def daily_report(
-        self,
-        target_date: Optional[str] = None,
-        author: Optional[str] = None,
-        repo: Optional[str] = None,
-    ) -> dict[str, Any]:
-        """Generate a daily report."""
-        if target_date is None:
-            target_date = datetime.utcnow().strftime("%Y-%m-%d")
-
-        start = f"{target_date}T00:00:00Z"
-        end = f"{target_date}T23:59:59Z"
-
-        commits = self.db.get_commits(repo=repo, author=author, since=start, until=end, limit=1000)
-        prs = self.db.get_pull_requests(repo=repo, author=author, since=start, limit=500)
-        issues = self.db.get_issues(repo=repo, since=start, limit=500)
-        reviews = self.db.get_reviews(repo=repo, author=author, since=start, limit=500)
-
-        prs_opened = len([p for p in prs if (p.get("created_at") or "").startswith(target_date)])
-        prs_merged = len([p for p in prs if (p.get("merged_at") or "").startswith(target_date)])
-        issues_opened = len([i for i in issues if (i.get("created_at") or "").startswith(target_date)])
-        issues_closed = len([i for i in issues if (i.get("closed_at") or "").startswith(target_date)])
-        lines_changed = sum(c.get("additions", 0) + c.get("deletions", 0) for c in commits)
-
-        # Build summary
-        parts: list[str] = []
-        parts.append(f"**{len(commits)} commit(s)**")
-        if prs_opened:
-            parts.append(f"{prs_opened} PR(s) opened")
-        if prs_merged:
-            parts.append(f"{prs_merged} PR(s) merged")
-        if issues_closed:
-            parts.append(f"{issues_closed} issue(s) closed")
-        if not parts:
-            parts.append("No activity recorded")
-
-        return {
-            "date": target_date,
-            "author": author or "all",
-            "commits": len(commits),
-            "prs_opened": prs_opened,
-            "prs_merged": prs_merged,
-            "issues_opened": issues_opened,
-            "issues_closed": issues_closed,
-            "reviews_given": len(reviews),
-            "lines_changed": lines_changed,
-            "summary": ", ".join(parts),
-            "commit_details": [
-                {"message": c.get("message", ""), "repo": c.get("repo", ""), "sha": c.get("sha", "")[:7]}
-                for c in commits[:10]
-            ],
-        }
-
-    # ── Weekly Report ────────────────────────────────────────────────
-
-    def weekly_report(
-        self,
-        week_start: Optional[str] = None,
-        repo: Optional[str] = None,
-    ) -> dict[str, Any]:
-        """Generate a weekly report."""
-        if week_start is None:
-            today = datetime.utcnow()
-            week_start = (today - timedelta(days=today.weekday())).strftime("%Y-%m-%d")
-
-        start_dt = datetime.strptime(week_start, "%Y-%m-%d")
-        end_dt = start_dt + timedelta(days=6)
-        week_end = end_dt.strftime("%Y-%m-%d")
-        since = start_dt.isoformat()
-
-        commits = self.db.get_commits(repo=repo, since=since, limit=2000)
-        prs = self.db.get_pull_requests(repo=repo, since=since, limit=500)
-        issues = self.db.get_issues(repo=repo, since=since, limit=500)
-
-        # Top contributors
-        author_counts: dict[str, int] = {}
-        for c in commits:
-            a = c.get("author", "unknown")
-            author_counts[a] = author_counts.get(a, 0) + 1
-        top = sorted(author_counts.items(), key=lambda x: x[1], reverse=True)[:5]
-
-        # Avg merge time
-        merge_hours: list[float] = []
-        for p in prs:
-            if p.get("merged_at") and p.get("created_at"):
-                from devpulse.core.analytics import _days_between
-                merge_hours.append(_days_between(p["created_at"], p["merged_at"]))
-        avg_merge = sum(merge_hours) / len(merge_hours) if merge_hours else 0.0
-
-        # Insights
-        insights_data = self.engine.generate_insights(days=7, repo=repo)
-
-        closed_issues = [i for i in issues if i.get("state") == "closed"]
-
-        return {
-            "week_start": week_start,
-            "week_end": week_end,
-            "authors": list(author_counts.keys()),
-            "total_commits": len(commits),
-            "total_prs": len(prs),
-            "total_issues_closed": len(closed_issues),
-            "avg_merge_time_hours": round(avg_merge, 1),
-            "top_contributors": [{"author": a, "commits": c} for a, c in top],
-            "insights": [i["message"] for i in insights_data],
-            "recommendations": [i["recommendation"] for i in insights_data],
-        }
-
-    # ── Monthly Report ───────────────────────────────────────────────
-
-    def monthly_report(
-        self,
-        year: Optional[int] = None,
-        month: Optional[int] = None,
-        repo: Optional[str] = None,
-    ) -> dict[str, Any]:
-        """Generate a monthly report."""
-        now = datetime.utcnow()
-        year = year or now.year
-        month = month or now.month
-        since = f"{year}-{month:02d}-01T00:00:00Z"
-
-        # Compute end of month
-        if month == 12:
-            until_dt = datetime(year + 1, 1, 1)
-        else:
-            until_dt = datetime(year, month + 1, 1)
-        until = until_dt.isoformat()
-
-        commits = self.db.get_commits(repo=repo, since=since, until=until, limit=5000)
-        prs = self.db.get_pull_requests(repo=repo, since=since, limit=1000)
-        issues = self.db.get_issues(repo=repo, since=since, limit=1000)
-
-        # Team health
-        health = self.engine.team_health(days=30, repo=repo)
-        insights = self.engine.generate_insights(days=30, repo=repo)
-
-        author_counts: dict[str, int] = {}
-        for c in commits:
-            a = c.get("author", "unknown")
-            author_counts[a] = author_counts.get(a, 0) + 1
-        top = sorted(author_counts.items(), key=lambda x: x[1], reverse=True)[:10]
-
-        return {
-            "period": f"{year}-{month:02d}",
-            "total_commits": len(commits),
-            "total_prs": len(prs),
-            "total_issues_closed": len([i for i in issues if i.get("state") == "closed"]),
-            "team_health_score": health.overall_score,
-            "top_contributors": [{"author": a, "commits": c} for a, c in top],
-            "insights": [i["message"] for i in insights],
-            "recommendations": [i["recommendation"] for i in insights],
-            "velocity_trend": health.velocity_trend,
-            "burnout_risks": health.burnout_risk,
-        }
-
-    # ── Output Formats ───────────────────────────────────────────────
-
-    def to_markdown(self, data: dict[str, Any], report_type: str = "daily") -> str:
-        """Convert report data to Markdown."""
-        lines: list[str] = []
-
-        if report_type == "daily":
-            lines.append(f"# Daily Report — {data['date']}")
-            lines.append("")
-            lines.append(f"**Author**: {data['author']}")
-            lines.append(f"**Summary**: {data['summary']}")
-            lines.append("")
-            lines.append("## Metrics")
-            lines.append("")
-            lines.append(f"| Metric | Value |")
-            lines.append(f"|--------|-------|")
-            lines.append(f"| Commits | {data['commits']} |")
-            lines.append(f"| PRs Opened | {data['prs_opened']} |")
-            lines.append(f"| PRs Merged | {data['prs_merged']} |")
-            lines.append(f"| Issues Opened | {data['issues_opened']} |")
-            lines.append(f"| Issues Closed | {data['issues_closed']} |")
-            lines.append(f"| Reviews Given | {data['reviews_given']} |")
-            lines.append(f"| Lines Changed | {data['lines_changed']} |")
-            lines.append("")
-            if data.get("commit_details"):
-                lines.append("## Recent Commits")
-                lines.append("")
-                for c in data["commit_details"]:
-                    lines.append(f"- `[{c['sha']}]` {c['message']} ({c['repo']})")
-                lines.append("")
-
-        elif report_type == "weekly":
-            lines.append(f"# Weekly Report — {data['week_start']} to {data['week_end']}")
-            lines.append("")
-            lines.append("## Overview")
-            lines.append("")
-            lines.append(f"- **Total Commits**: {data['total_commits']}")
-            lines.append(f"- **Total PRs**: {data['total_prs']}")
-            lines.append(f"- **Issues Closed**: {data['total_issues_closed']}")
-            lines.append(f"- **Avg Merge Time**: {data['avg_merge_time_hours']}h")
-            lines.append("")
-            lines.append("## Top Contributors")
-            lines.append("")
-            for tc in data["top_contributors"]:
-                lines.append(f"- **{tc['author']}**: {tc['commits']} commits")
-            lines.append("")
-            if data.get("insights"):
-                lines.append("## AI Insights")
-                lines.append("")
-                for ins in data["insights"]:
-                    lines.append(f"- {ins}")
-                lines.append("")
-            if data.get("recommendations"):
-                lines.append("## Recommendations")
-                lines.append("")
-                for rec in data["recommendations"]:
-                    lines.append(f"- {rec}")
-                lines.append("")
-
-        elif report_type == "monthly":
-            lines.append(f"# Monthly Report — {data['period']}")
-            lines.append("")
-            lines.append("## Overview")
-            lines.append("")
-            lines.append(f"- **Total Commits**: {data['total_commits']}")
-            lines.append(f"- **Total PRs**: {data['total_prs']}")
-            lines.append(f"- **Issues Closed**: {data['total_issues_closed']}")
-            lines.append(f"- **Team Health Score**: {data['team_health_score']}/100")
-            lines.append(f"- **Velocity Trend**: {data['velocity_trend']}")
-            lines.append("")
-            lines.append("## Top Contributors")
-            lines.append("")
-            for tc in data["top_contributors"]:
-                lines.append(f"- **{tc['author']}**: {tc['commits']} commits")
-            lines.append("")
-            if data.get("burnout_risks"):
-                lines.append("## Burnout Risk")
-                lines.append("")
-                for name, risk in data["burnout_risks"].items():
-                    emoji = ":red_circle:" if risk >= 0.6 else ":yellow_circle:" if risk >= 0.3 else ":green_circle:"
-                    lines.append(f"- {emoji} **{name}**: {risk:.0%}")
-                lines.append("")
-            if data.get("insights"):
-                lines.append("## AI Insights")
-                lines.append("")
-                for ins in data["insights"]:
-                    lines.append(f"- {ins}")
-                lines.append("")
-
-        return "\n".join(lines)
-
-    def to_json(self, data: dict[str, Any]) -> str:
-        """Convert report data to JSON."""
-        return json.dumps(data, indent=2, default=str)
-
-    def to_html(self, data: dict[str, Any], report_type: str = "daily") -> str:
-        """Convert report data to a standalone HTML page."""
-        md_content = self.to_markdown(data, report_type)
-        # Simple markdown-to-HTML conversion for key elements
-        html_body = _md_to_html(md_content)
-
-        html = f"""<!DOCTYPE html>
-<html lang="en">
-<head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>DevPulse Report</title>
-    <style>
-        :root {{
-            --bg: #0d1117;
-            --card: #161b22;
-            --border: #30363d;
-            --text: #c9d1d9;
-            --heading: #f0f6fc;
-            --accent: #58a6ff;
-            --green: #3fb950;
-            --yellow: #d29922;
-            --red: #f85149;
-        }}
-        * {{ margin: 0; padding: 0; box-sizing: border-box; }}
-        body {{
-            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif;
-            background: var(--bg);
-            color: var(--text);
-            line-height: 1.6;
-            padding: 2rem;
-            max-width: 960px;
-            margin: 0 auto;
-        }}
-        h1 {{ color: var(--heading); margin-bottom: 1rem; border-bottom: 1px solid var(--border); padding-bottom: 0.5rem; }}
-        h2 {{ color: var(--accent); margin-top: 1.5rem; margin-bottom: 0.5rem; }}
-        table {{ border-collapse: collapse; width: 100%; margin: 1rem 0; }}
-        th, td {{ border: 1px solid var(--border); padding: 0.5rem 1rem; text-align: left; }}
-        th {{ background: var(--card); color: var(--heading); }}
-        td {{ background: var(--card); }}
-        ul {{ padding-left: 1.5rem; }}
-        li {{ margin: 0.25rem 0; }}
-        strong {{ color: var(--heading); }}
-        code {{ background: var(--card); padding: 0.15rem 0.4rem; border-radius: 3px; font-size: 0.9em; }}
-        .header {{ text-align: center; margin-bottom: 2rem; }}
-        .header p {{ color: var(--accent); }}
-        .metric-grid {{ display: grid; grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); gap: 1rem; margin: 1rem 0; }}
-        .metric-card {{ background: var(--card); border: 1px solid var(--border); border-radius: 8px; padding: 1rem; text-align: center; }}
-        .metric-card .value {{ font-size: 2rem; font-weight: bold; color: var(--heading); }}
-        .metric-card .label {{ font-size: 0.85rem; color: var(--text); }}
-        .badge {{ display: inline-block; padding: 0.2rem 0.6rem; border-radius: 12px; font-size: 0.8rem; font-weight: 600; }}
-        .badge-green {{ background: #1a3a2a; color: var(--green); }}
-        .badge-yellow {{ background: #3a2a1a; color: var(--yellow); }}
-        .badge-red {{ background: #3a1a1a; color: var(--red); }}
-    </style>
-</head>
-<body>
-    <div class="header">
-        <h1>DevPulse Report</h1>
-        <p>AI-Powered Developer Productivity Dashboard</p>
-    </div>
-    {html_body}
-</body>
-</html>"""
-        return html
-
-    # ── Save to File ─────────────────────────────────────────────────
-
-    def save_report(
-        self,
-        data: dict[str, Any],
-        report_type: str,
-        fmt: str = "markdown",
-    ) -> str:
-        """Save report to file and return the path."""
-        period = data.get("date", data.get("week_start", data.get("period", "unknown")))
-
-        if fmt == "json":
-            content = self.to_json(data)
-            ext = "json"
-        elif fmt == "html":
-            content = self.to_html(data, report_type)
-            ext = "html"
-        else:
-            content = self.to_markdown(data, report_type)
-            ext = "md"
-
-        filename = f"{report_type}_report_{period}.{ext}"
-        filepath = os.path.join(self.reports_dir, filename)
-
-        with open(filepath, "w", encoding="utf-8") as f:
-            f.write(content)
-
-        # Cache in database
-        self.db.save_report(report_type, period, content)
-
-        return filepath
-
-
-def _md_to_html(md: str) -> str:
-    """Minimal Markdown to HTML converter."""
-    lines = md.split("\n")
-    html_parts: list[str] = []
-    in_list = False
-    in_table = False
-
-    for line in lines:
-        stripped = line.strip()
-
-        if stripped.startswith("# "):
-            if in_list:
-                html_parts.append("</ul>")
-                in_list = False
-            html_parts.append(f"<h1>{stripped[2:]}</h1>")
-        elif stripped.startswith("## "):
-            if in_list:
-                html_parts.append("</ul>")
-                in_list = False
-            html_parts.append(f"<h2>{stripped[3:]}</h2>")
-        elif stripped.startswith("| ") and "---" not in stripped:
-            if not in_table:
-                html_parts.append("<table>")
-                in_table = True
-            cells = [c.strip() for c in stripped.split("|")[1:-1]]
-            tag = "th" if not html_parts or not any("<td>" in p for p in html_parts[-5:]) else "td"
-            row = "".join(f"<{tag}>{c}</{tag}>" for c in cells)
-            html_parts.append(f"<tr>{row}</tr>")
-        elif stripped.startswith("- "):
-            if in_table:
-                html_parts.append("</table>")
-                in_table = False
-            if not in_list:
-                html_parts.append("<ul>")
-                in_list = True
-            content = stripped[2:]
-            # Bold
-            content = content.replace("**", "<strong>", 1).replace("**", "</strong>", 1)
-            # Code
-            if "`" in content:
-                parts = content.split("`")
-                content = parts[0] + "".join(
-                    f"<code>{parts[i]}</code>" + parts[i + 1] if i + 1 < len(parts) else ""
-                    for i in range(1, len(parts), 2)
-                )
-            html_parts.append(f"<li>{content}</li>")
-        elif stripped == "":
-            if in_list:
-                html_parts.append("</ul>")
-                in_list = False
-            if in_table:
-                html_parts.append("</table>")
-                in_table = False
-            html_parts.append("<br>")
-        else:
-            if in_list:
-                html_parts.append("</ul>")
-                in_list = False
-            if in_table:
-                html_parts.append("</table>")
-                in_table = False
-            content = stripped
-            content = content.replace("**", "<strong>", 1).replace("**", "</strong>", 1)
-            html_parts.append(f"<p>{content}</p>")
-
-    if in_list:
-        html_parts.append("</ul>")
-    if in_table:
-        html_parts.append("</table>")
-
-    return "\n".join(html_parts)
+"""Report generator — produces Markdown, JSON, and HTML reports."""
+
+import json
+import os
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Any, Optional
+
+from jinja2 import Environment, FileSystemLoader, BaseLoader
+
+from devpulse.core.database import Database
+from devpulse.core.analytics import AnalyticsEngine
+from devpulse.core.config import get_settings
+
+
+class ReportGenerator:
+    """Generate daily, weekly, and monthly reports in multiple formats."""
+
+    def __init__(self, db: Optional[Database] = None) -> None:
+        self.db = db or Database()
+        self.engine = AnalyticsEngine(db=self.db)
+        settings = get_settings()
+        self.reports_dir = settings.reports_dir
+        Path(self.reports_dir).mkdir(parents=True, exist_ok=True)
+
+        # Set up Jinja2 for HTML reports
+        template_dir = Path(__file__).parent.parent / "templates"
+        if template_dir.exists():
+            self.jinja_env = Environment(loader=FileSystemLoader(str(template_dir)))
+        else:
+            self.jinja_env = Environment(loader=BaseLoader())
+
+    # ── Daily Report ─────────────────────────────────────────────────
+
+    def daily_report(
+        self,
+        target_date: Optional[str] = None,
+        author: Optional[str] = None,
+        repo: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """Generate a daily report."""
+        if target_date is None:
+            target_date = datetime.utcnow().strftime("%Y-%m-%d")
+
+        start = f"{target_date}T00:00:00Z"
+        end = f"{target_date}T23:59:59Z"
+
+        commits = self.db.get_commits(repo=repo, author=author, since=start, until=end, limit=1000)
+        prs = self.db.get_pull_requests(repo=repo, author=author, since=start, limit=500)
+        issues = self.db.get_issues(repo=repo, since=start, limit=500)
+        reviews = self.db.get_reviews(repo=repo, author=author, since=start, limit=500)
+
+        prs_opened = len([p for p in prs if (p.get("created_at") or "").startswith(target_date)])
+        prs_merged = len([p for p in prs if (p.get("merged_at") or "").startswith(target_date)])
+        issues_opened = len([i for i in issues if (i.get("created_at") or "").startswith(target_date)])
+        issues_closed = len([i for i in issues if (i.get("closed_at") or "").startswith(target_date)])
+        lines_changed = sum(c.get("additions", 0) + c.get("deletions", 0) for c in commits)
+
+        # Build summary
+        parts: list[str] = []
+        parts.append(f"**{len(commits)} commit(s)**")
+        if prs_opened:
+            parts.append(f"{prs_opened} PR(s) opened")
+        if prs_merged:
+            parts.append(f"{prs_merged} PR(s) merged")
+        if issues_closed:
+            parts.append(f"{issues_closed} issue(s) closed")
+        if not parts:
+            parts.append("No activity recorded")
+
+        return {
+            "date": target_date,
+            "author": author or "all",
+            "commits": len(commits),
+            "prs_opened": prs_opened,
+            "prs_merged": prs_merged,
+            "issues_opened": issues_opened,
+            "issues_closed": issues_closed,
+            "reviews_given": len(reviews),
+            "lines_changed": lines_changed,
+            "summary": ", ".join(parts),
+            "commit_details": [
+                {"message": c.get("message", ""), "repo": c.get("repo", ""), "sha": c.get("sha", "")[:7]}
+                for c in commits[:10]
+            ],
+        }
+
+    # ── Weekly Report ────────────────────────────────────────────────
+
+    def weekly_report(
+        self,
+        week_start: Optional[str] = None,
+        repo: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """Generate a weekly report."""
+        if week_start is None:
+            today = datetime.utcnow()
+            week_start = (today - timedelta(days=today.weekday())).strftime("%Y-%m-%d")
+
+        start_dt = datetime.strptime(week_start, "%Y-%m-%d")
+        end_dt = start_dt + timedelta(days=6)
+        week_end = end_dt.strftime("%Y-%m-%d")
+        since = start_dt.isoformat()
+
+        commits = self.db.get_commits(repo=repo, since=since, limit=2000)
+        prs = self.db.get_pull_requests(repo=repo, since=since, limit=500)
+        issues = self.db.get_issues(repo=repo, since=since, limit=500)
+
+        # Top contributors
+        author_counts: dict[str, int] = {}
+        for c in commits:
+            a = c.get("author", "unknown")
+            author_counts[a] = author_counts.get(a, 0) + 1
+        top = sorted(author_counts.items(), key=lambda x: x[1], reverse=True)[:5]
+
+        # Avg merge time
+        merge_hours: list[float] = []
+        for p in prs:
+            if p.get("merged_at") and p.get("created_at"):
+                from devpulse.core.analytics import _days_between
+                merge_hours.append(_days_between(p["created_at"], p["merged_at"]))
+        avg_merge = sum(merge_hours) / len(merge_hours) if merge_hours else 0.0
+
+        # Insights
+        insights_data = self.engine.generate_insights(days=7, repo=repo)
+
+        closed_issues = [i for i in issues if i.get("state") == "closed"]
+
+        return {
+            "week_start": week_start,
+            "week_end": week_end,
+            "authors": list(author_counts.keys()),
+            "total_commits": len(commits),
+            "total_prs": len(prs),
+            "total_issues_closed": len(closed_issues),
+            "avg_merge_time_hours": round(avg_merge, 1),
+            "top_contributors": [{"author": a, "commits": c} for a, c in top],
+            "insights": [i["message"] for i in insights_data],
+            "recommendations": [i["recommendation"] for i in insights_data],
+        }
+
+    # ── Monthly Report ───────────────────────────────────────────────
+
+    def monthly_report(
+        self,
+        year: Optional[int] = None,
+        month: Optional[int] = None,
+        repo: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """Generate a monthly report."""
+        now = datetime.utcnow()
+        year = year or now.year
+        month = month or now.month
+        since = f"{year}-{month:02d}-01T00:00:00Z"
+
+        # Compute end of month
+        if month == 12:
+            until_dt = datetime(year + 1, 1, 1)
+        else:
+            until_dt = datetime(year, month + 1, 1)
+        until = until_dt.isoformat()
+
+        commits = self.db.get_commits(repo=repo, since=since, until=until, limit=5000)
+        prs = self.db.get_pull_requests(repo=repo, since=since, limit=1000)
+        issues = self.db.get_issues(repo=repo, since=since, limit=1000)
+
+        # Team health
+        health = self.engine.team_health(days=30, repo=repo)
+        insights = self.engine.generate_insights(days=30, repo=repo)
+
+        author_counts: dict[str, int] = {}
+        for c in commits:
+            a = c.get("author", "unknown")
+            author_counts[a] = author_counts.get(a, 0) + 1
+        top = sorted(author_counts.items(), key=lambda x: x[1], reverse=True)[:10]
+
+        return {
+            "period": f"{year}-{month:02d}",
+            "total_commits": len(commits),
+            "total_prs": len(prs),
+            "total_issues_closed": len([i for i in issues if i.get("state") == "closed"]),
+            "team_health_score": health.overall_score,
+            "top_contributors": [{"author": a, "commits": c} for a, c in top],
+            "insights": [i["message"] for i in insights],
+            "recommendations": [i["recommendation"] for i in insights],
+            "velocity_trend": health.velocity_trend,
+            "burnout_risks": health.burnout_risk,
+        }
+
+    # ── Output Formats ───────────────────────────────────────────────
+
+    def to_markdown(self, data: dict[str, Any], report_type: str = "daily") -> str:
+        """Convert report data to Markdown."""
+        lines: list[str] = []
+
+        if report_type == "daily":
+            lines.append(f"# Daily Report — {data['date']}")
+            lines.append("")
+            lines.append(f"**Author**: {data['author']}")
+            lines.append(f"**Summary**: {data['summary']}")
+            lines.append("")
+            lines.append("## Metrics")
+            lines.append("")
+            lines.append(f"| Metric | Value |")
+            lines.append(f"|--------|-------|")
+            lines.append(f"| Commits | {data['commits']} |")
+            lines.append(f"| PRs Opened | {data['prs_opened']} |")
+            lines.append(f"| PRs Merged | {data['prs_merged']} |")
+            lines.append(f"| Issues Opened | {data['issues_opened']} |")
+            lines.append(f"| Issues Closed | {data['issues_closed']} |")
+            lines.append(f"| Reviews Given | {data['reviews_given']} |")
+            lines.append(f"| Lines Changed | {data['lines_changed']} |")
+            lines.append("")
+            if data.get("commit_details"):
+                lines.append("## Recent Commits")
+                lines.append("")
+                for c in data["commit_details"]:
+                    lines.append(f"- `[{c['sha']}]` {c['message']} ({c['repo']})")
+                lines.append("")
+
+        elif report_type == "weekly":
+            lines.append(f"# Weekly Report — {data['week_start']} to {data['week_end']}")
+            lines.append("")
+            lines.append("## Overview")
+            lines.append("")
+            lines.append(f"- **Total Commits**: {data['total_commits']}")
+            lines.append(f"- **Total PRs**: {data['total_prs']}")
+            lines.append(f"- **Issues Closed**: {data['total_issues_closed']}")
+            lines.append(f"- **Avg Merge Time**: {data['avg_merge_time_hours']}h")
+            lines.append("")
+            lines.append("## Top Contributors")
+            lines.append("")
+            for tc in data["top_contributors"]:
+                lines.append(f"- **{tc['author']}**: {tc['commits']} commits")
+            lines.append("")
+            if data.get("insights"):
+                lines.append("## AI Insights")
+                lines.append("")
+                for ins in data["insights"]:
+                    lines.append(f"- {ins}")
+                lines.append("")
+            if data.get("recommendations"):
+                lines.append("## Recommendations")
+                lines.append("")
+                for rec in data["recommendations"]:
+                    lines.append(f"- {rec}")
+                lines.append("")
+
+        elif report_type == "monthly":
+            lines.append(f"# Monthly Report — {data['period']}")
+            lines.append("")
+            lines.append("## Overview")
+            lines.append("")
+            lines.append(f"- **Total Commits**: {data['total_commits']}")
+            lines.append(f"- **Total PRs**: {data['total_prs']}")
+            lines.append(f"- **Issues Closed**: {data['total_issues_closed']}")
+            lines.append(f"- **Team Health Score**: {data['team_health_score']}/100")
+            lines.append(f"- **Velocity Trend**: {data['velocity_trend']}")
+            lines.append("")
+            lines.append("## Top Contributors")
+            lines.append("")
+            for tc in data["top_contributors"]:
+                lines.append(f"- **{tc['author']}**: {tc['commits']} commits")
+            lines.append("")
+            if data.get("burnout_risks"):
+                lines.append("## Burnout Risk")
+                lines.append("")
+                for name, risk in data["burnout_risks"].items():
+                    emoji = ":red_circle:" if risk >= 0.6 else ":yellow_circle:" if risk >= 0.3 else ":green_circle:"
+                    lines.append(f"- {emoji} **{name}**: {risk:.0%}")
+                lines.append("")
+            if data.get("insights"):
+                lines.append("## AI Insights")
+                lines.append("")
+                for ins in data["insights"]:
+                    lines.append(f"- {ins}")
+                lines.append("")
+
+        return "\n".join(lines)
+
+    def to_json(self, data: dict[str, Any]) -> str:
+        """Convert report data to JSON."""
+        return json.dumps(data, indent=2, default=str)
+
+    def to_html(self, data: dict[str, Any], report_type: str = "daily") -> str:
+        """Convert report data to a standalone HTML page."""
+        md_content = self.to_markdown(data, report_type)
+        # Simple markdown-to-HTML conversion for key elements
+        html_body = _md_to_html(md_content)
+
+        html = f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>DevPulse Report</title>
+    <style>
+        :root {{
+            --bg: #0d1117;
+            --card: #161b22;
+            --border: #30363d;
+            --text: #c9d1d9;
+            --heading: #f0f6fc;
+            --accent: #58a6ff;
+            --green: #3fb950;
+            --yellow: #d29922;
+            --red: #f85149;
+        }}
+        * {{ margin: 0; padding: 0; box-sizing: border-box; }}
+        body {{
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif;
+            background: var(--bg);
+            color: var(--text);
+            line-height: 1.6;
+            padding: 2rem;
+            max-width: 960px;
+            margin: 0 auto;
+        }}
+        h1 {{ color: var(--heading); margin-bottom: 1rem; border-bottom: 1px solid var(--border); padding-bottom: 0.5rem; }}
+        h2 {{ color: var(--accent); margin-top: 1.5rem; margin-bottom: 0.5rem; }}
+        table {{ border-collapse: collapse; width: 100%; margin: 1rem 0; }}
+        th, td {{ border: 1px solid var(--border); padding: 0.5rem 1rem; text-align: left; }}
+        th {{ background: var(--card); color: var(--heading); }}
+        td {{ background: var(--card); }}
+        ul {{ padding-left: 1.5rem; }}
+        li {{ margin: 0.25rem 0; }}
+        strong {{ color: var(--heading); }}
+        code {{ background: var(--card); padding: 0.15rem 0.4rem; border-radius: 3px; font-size: 0.9em; }}
+        .header {{ text-align: center; margin-bottom: 2rem; }}
+        .header p {{ color: var(--accent); }}
+        .metric-grid {{ display: grid; grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); gap: 1rem; margin: 1rem 0; }}
+        .metric-card {{ background: var(--card); border: 1px solid var(--border); border-radius: 8px; padding: 1rem; text-align: center; }}
+        .metric-card .value {{ font-size: 2rem; font-weight: bold; color: var(--heading); }}
+        .metric-card .label {{ font-size: 0.85rem; color: var(--text); }}
+        .badge {{ display: inline-block; padding: 0.2rem 0.6rem; border-radius: 12px; font-size: 0.8rem; font-weight: 600; }}
+        .badge-green {{ background: #1a3a2a; color: var(--green); }}
+        .badge-yellow {{ background: #3a2a1a; color: var(--yellow); }}
+        .badge-red {{ background: #3a1a1a; color: var(--red); }}
+    </style>
+</head>
+<body>
+    <div class="header">
+        <h1>DevPulse Report</h1>
+        <p>AI-Powered Developer Productivity Dashboard</p>
+    </div>
+    {html_body}
+</body>
+</html>"""
+        return html
+
+    # ── Save to File ─────────────────────────────────────────────────
+
+    def save_report(
+        self,
+        data: dict[str, Any],
+        report_type: str,
+        fmt: str = "markdown",
+    ) -> str:
+        """Save report to file and return the path."""
+        period = data.get("date", data.get("week_start", data.get("period", "unknown")))
+
+        if fmt == "json":
+            content = self.to_json(data)
+            ext = "json"
+        elif fmt == "html":
+            content = self.to_html(data, report_type)
+            ext = "html"
+        else:
+            content = self.to_markdown(data, report_type)
+            ext = "md"
+
+        filename = f"{report_type}_report_{period}.{ext}"
+        filepath = os.path.join(self.reports_dir, filename)
+
+        with open(filepath, "w", encoding="utf-8") as f:
+            f.write(content)
+
+        # Cache in database
+        self.db.save_report(report_type, period, content)
+
+        return filepath
+
+
+def _md_to_html(md: str) -> str:
+    """Minimal Markdown to HTML converter."""
+    lines = md.split("\n")
+    html_parts: list[str] = []
+    in_list = False
+    in_table = False
+
+    for line in lines:
+        stripped = line.strip()
+
+        if stripped.startswith("# "):
+            if in_list:
+                html_parts.append("</ul>")
+                in_list = False
+            html_parts.append(f"<h1>{stripped[2:]}</h1>")
+        elif stripped.startswith("## "):
+            if in_list:
+                html_parts.append("</ul>")
+                in_list = False
+            html_parts.append(f"<h2>{stripped[3:]}</h2>")
+        elif stripped.startswith("| ") and "---" not in stripped:
+            if not in_table:
+                html_parts.append("<table>")
+                in_table = True
+            cells = [c.strip() for c in stripped.split("|")[1:-1]]
+            tag = "th" if not html_parts or not any("<td>" in p for p in html_parts[-5:]) else "td"
+            row = "".join(f"<{tag}>{c}</{tag}>" for c in cells)
+            html_parts.append(f"<tr>{row}</tr>")
+        elif stripped.startswith("- "):
+            if in_table:
+                html_parts.append("</table>")
+                in_table = False
+            if not in_list:
+                html_parts.append("<ul>")
+                in_list = True
+            content = stripped[2:]
+            # Bold
+            content = content.replace("**", "<strong>", 1).replace("**", "</strong>", 1)
+            # Code
+            if "`" in content:
+                parts = content.split("`")
+                content = parts[0] + "".join(
+                    f"<code>{parts[i]}</code>" + parts[i + 1] if i + 1 < len(parts) else ""
+                    for i in range(1, len(parts), 2)
+                )
+            html_parts.append(f"<li>{content}</li>")
+        elif stripped == "":
+            if in_list:
+                html_parts.append("</ul>")
+                in_list = False
+            if in_table:
+                html_parts.append("</table>")
+                in_table = False
+            html_parts.append("<br>")
+        else:
+            if in_list:
+                html_parts.append("</ul>")
+                in_list = False
+            if in_table:
+                html_parts.append("</table>")
+                in_table = False
+            content = stripped
+            content = content.replace("**", "<strong>", 1).replace("**", "</strong>", 1)
+            html_parts.append(f"<p>{content}</p>")
+
+    if in_list:
+        html_parts.append("</ul>")
+    if in_table:
+        html_parts.append("</table>")
+
+    return "\n".join(html_parts)