Sprint Retrospective

{
  "sprint": {
    "name": "Sprint 23",
    "start_date": "2026-03-04",
    "end_date": "2026-03-18",
    "team_size": 5
  },
  "velocity": {
    "total_commits": 115,
    "loc_added": 4823,
    "loc_removed": 1976,
    "loc_net": 2847,
    "prs_merged": 14,
    "avg_pr_size_loc": 203,
    "throughput_per_day": 8.2,
    "cycle_time_hours": 18.3,
    "lead_time_hours": 22.1,
    "deploy_frequency_per_day": 1.0,
    "commit_types": {
      "feat": 48,
      "fix": 21,
      "docs": 16,
      "refactor": 14,
      "test": 9,
      "chore": 7
    },
    "sessions": {
      "deep_work": 18,
      "focused": 24,
      "micro": 15
    }
  },
  "contributors": [
    {
      "email": "alice@example.com",
      "commits": 34,
      "loc_added": 1204,
      "loc_removed": 387,
      "files_touched": 28,
      "peak_hours": [10, 11, 14, 15],
      "specialization": {"backend": 0.67, "tests": 0.22, "docs": 0.11},
      "sessions": {"deep_work": 5, "focused": 4, "micro": 3},
      "consistency_score": 0.82
    },
    {
      "email": "bob@example.com",
      "commits": 28,
      "loc_added": 1567,
      "loc_removed": 823,
      "files_touched": 35,
      "peak_hours": [9, 10, 11, 13, 14],
      "specialization": {"frontend": 0.55, "backend": 0.30, "infra": 0.15},
      "sessions": {"deep_work": 6, "focused": 5, "micro": 2},
      "consistency_score": 0.75
    },
    {
      "email": "carol@example.com",
      "commits": 25,
      "loc_added": 987,
      "loc_removed": 412,
      "files_touched": 22,
      "peak_hours": [11, 14, 15, 16],
      "specialization": {"backend": 0.48, "data": 0.32, "tests": 0.20},
      "sessions": {"deep_work": 4, "focused": 7, "micro": 3},
      "consistency_score": 0.88
    }
  ],
  "churn": {
    "hotspots": [
      {"file": "src/api/handlers.py", "changes": 12, "authors": 3, "churn_score": 8.4},
      {"file": "src/models/user.py", "changes": 8, "authors": 2, "churn_score": 5.2},
      {"file": "src/ui/dashboard.tsx", "changes": 7, "authors": 2, "churn_score": 4.8}
    ],
    "churn_rate": 0.34,
    "test_to_prod_ratio": 0.38,
    "refactor_frequency": 0.12,
    "hotspot_concentration": 0.32
  },
  "previous_action_items": [
    {"text": "Reduce average PR size below 250 LOC", "status": "done"},
    {"text": "Add integration tests for auth module", "status": "in_progress"},
    {"text": "Schedule weekly knowledge-sharing sessions", "status": "not_started"}
  ]
}

#!/usr/bin/env python3
"""
Code Churn Analyzer

Identifies file hotspots, calculates churn rates, detects code oscillation,
maps churn to directories/modules, and flags potential refactoring candidates.

Usage:
    python code_churn_analyzer.py --days 14
    python code_churn_analyzer.py --days 14 --top 20 --detect-oscillation
    python code_churn_analyzer.py --days 14 --path src/ --format json

Standard library only.
"""

import argparse
import json
import subprocess
import sys
from collections import defaultdict
from datetime import datetime, timedelta
from typing import Any


# --- Git Helpers ---

def run_git(args: list[str], repo: str = ".") -> str:
    cmd = ["git", "-C", repo] + args
    result = subprocess.run(cmd, capture_output=True, text=True, timeout=60)
    if result.returncode != 0:
        return ""
    return result.stdout.strip()


def parse_datetime(iso_str: str) -> datetime:
    clean = iso_str.strip()
    if len(clean) > 19 and (clean[-3] == ":" and (clean[-6] == "+" or clean[-6] == "-")):
        clean = clean[:-3] + clean[-2:]
    try:
        return datetime.strptime(clean, "%Y-%m-%dT%H:%M:%S%z")
    except ValueError:
        try:
            return datetime.strptime(clean[:19], "%Y-%m-%dT%H:%M:%S")
        except ValueError:
            return datetime.now()


# --- Data Collection ---

def get_file_changes(since: str, until: str, repo: str = ".",
                     path_filter: str | None = None) -> list[dict]:
    """Get per-commit file-level change data."""
    log = run_git([
        "log", "--all", f"--since={since}", f"--until={until}",
        "--pretty=format:COMMIT|%H|%ae|%aI|%s", "--numstat", "--no-merges"
    ], repo)
    if not log:
        return []

    commits = []
    current = None

    for line in log.split("\n"):
        line = line.strip()
        if not line:
            continue
        if line.startswith("COMMIT|"):
            if current:
                commits.append(current)
            parts = line.split("|", 4)
            if len(parts) < 5:
                current = None
                continue
            current = {
                "hash": parts[1],
                "author": parts[2],
                "date": parts[3],
                "subject": parts[4],
                "files": [],
            }
        elif current and "\t" in line:
            parts = line.split("\t")
            if len(parts) >= 3:
                filepath = parts[2]
                if path_filter and not filepath.startswith(path_filter):
                    continue
                try:
                    added = int(parts[0]) if parts[0] != "-" else 0
                    removed = int(parts[1]) if parts[1] != "-" else 0
                except ValueError:
                    added = 0
                    removed = 0
                current["files"].append({
                    "path": filepath,
                    "added": added,
                    "removed": removed,
                })

    if current:
        commits.append(current)

    return commits


# --- Hotspot Analysis ---

def compute_hotspots(commits: list[dict], total_days: int, top_n: int = 15) -> list[dict]:
    """Compute file hotspots ranked by composite churn score."""
    file_data = defaultdict(lambda: {
        "changes": 0,
        "authors": set(),
        "total_added": 0,
        "total_removed": 0,
        "last_changed": None,
        "commit_dates": [],
    })

    for c in commits:
        commit_dt = parse_datetime(c["date"])
        for f in c.get("files", []):
            path = f["path"]
            fd = file_data[path]
            fd["changes"] += 1
            fd["authors"].add(c["author"])
            fd["total_added"] += f["added"]
            fd["total_removed"] += f["removed"]
            fd["commit_dates"].append(commit_dt)
            if fd["last_changed"] is None or commit_dt > fd["last_changed"]:
                fd["last_changed"] = commit_dt

    # Compute recency weight (more recent = higher weight)
    now = datetime.now()
    hotspots = []
    for path, fd in file_data.items():
        author_count = len(fd["authors"])
        changes = fd["changes"]

        # Recency: days since last change, mapped to 0-1
        if fd["last_changed"]:
            try:
                last = fd["last_changed"].replace(tzinfo=None)
                days_ago = (now - last).days
            except (TypeError, AttributeError):
                days_ago = total_days
        else:
            days_ago = total_days
        recency = max(0, 1 - (days_ago / max(total_days, 1)))

        # Composite score
        churn_score = round(changes * (1 + 0.3 * (author_count - 1)) * (0.5 + 0.5 * recency), 1)
        churn_rate = round(changes / max(total_days, 1), 2)

        hotspots.append({
            "file": path,
            "changes": changes,
            "authors": sorted(fd["authors"]),
            "author_count": author_count,
            "loc_added": fd["total_added"],
            "loc_removed": fd["total_removed"],
            "loc_churn": fd["total_added"] + fd["total_removed"],
            "churn_rate": churn_rate,
            "churn_score": churn_score,
        })

    hotspots.sort(key=lambda x: -x["churn_score"])
    return hotspots[:top_n]


# --- Directory Churn ---

def compute_directory_churn(commits: list[dict]) -> list[dict]:
    """Aggregate churn by top-level directory."""
    dir_data = defaultdict(lambda: {
        "changes": 0, "files": set(), "authors": set(),
        "loc_added": 0, "loc_removed": 0,
    })

    for c in commits:
        for f in c.get("files", []):
            path = f["path"]
            parts = path.split("/")
            directory = parts[0] if len(parts) > 1 else "."
            dd = dir_data[directory]
            dd["changes"] += 1
            dd["files"].add(path)
            dd["authors"].add(c["author"])
            dd["loc_added"] += f["added"]
            dd["loc_removed"] += f["removed"]

    result = []
    for directory, dd in dir_data.items():
        result.append({
            "directory": directory,
            "changes": dd["changes"],
            "unique_files": len(dd["files"]),
            "authors": sorted(dd["authors"]),
            "author_count": len(dd["authors"]),
            "loc_added": dd["loc_added"],
            "loc_removed": dd["loc_removed"],
        })

    result.sort(key=lambda x: -x["changes"])
    return result


# --- Oscillation Detection ---

def detect_oscillation(commits: list[dict], threshold: int = 3) -> list[dict]:
    """Detect files with add-remove oscillation patterns.

    Looks for files where lines are added then removed (or vice versa) in
    alternating commits, indicating unclear requirements or design churn.
    """
    # Track per-file add/remove patterns in chronological order
    file_patterns = defaultdict(list)

    # Sort commits by date
    sorted_commits = sorted(commits, key=lambda c: c["date"])

    for c in sorted_commits:
        for f in c.get("files", []):
            path = f["path"]
            added = f["added"]
            removed = f["removed"]
            if added > removed:
                file_patterns[path].append("add")
            elif removed > added:
                file_patterns[path].append("remove")
            else:
                file_patterns[path].append("neutral")

    oscillating = []
    for path, patterns in file_patterns.items():
        if len(patterns) < threshold:
            continue

        # Count direction changes
        changes = 0
        for i in range(1, len(patterns)):
            if patterns[i] != patterns[i - 1] and patterns[i] != "neutral" and patterns[i - 1] != "neutral":
                changes += 1

        if changes >= threshold - 1:
            oscillating.append({
                "file": path,
                "total_changes": len(patterns),
                "direction_changes": changes,
                "pattern": patterns,
                "oscillation_ratio": round(changes / max(len(patterns) - 1, 1), 2),
            })

    oscillating.sort(key=lambda x: -x["direction_changes"])
    return oscillating


# --- Code Health Indicators ---

def classify_commit_type(subject: str) -> str:
    s = subject.lower().strip()
    prefixes = [
        ("feat", "feat"), ("fix", "fix"), ("docs", "docs"),
        ("refactor", "refactor"), ("test", "test"), ("chore", "chore"),
        ("style", "style"), ("perf", "perf"), ("ci", "ci"),
        ("build", "build"), ("revert", "revert"),
    ]
    for prefix, label in prefixes:
        if s.startswith(prefix + ":") or s.startswith(prefix + "("):
            return label
    return "other"


def is_test_file(path: str) -> bool:
    p = path.lower()
    test_indicators = ["test_", "_test.", ".test.", ".spec.", "_spec.", "__tests__/", "/test/", "/tests/", "/spec/"]
    return any(ind in p for ind in test_indicators)


def compute_health_indicators(commits: list[dict], hotspots: list[dict],
                              total_days: int) -> dict:
    """Compute aggregate code health indicators."""
    total_commits = len(commits)

    # Commit type counts
    type_counts = defaultdict(int)
    for c in commits:
        t = classify_commit_type(c["subject"])
        type_counts[t] += 1

    # Refactor frequency
    refactor_freq = round(type_counts.get("refactor", 0) / max(total_commits, 1), 2)

    # Test-to-production ratio
    test_changes = 0
    prod_changes = 0
    all_files = set()

    for c in commits:
        for f in c.get("files", []):
            all_files.add(f["path"])
            total_loc = f["added"] + f["removed"]
            if is_test_file(f["path"]):
                test_changes += total_loc
            else:
                prod_changes += total_loc

    test_ratio = round(test_changes / max(prod_changes, 1), 2)

    # Hotspot concentration
    total_file_changes = sum(1 for c in commits for _ in c.get("files", []))
    if hotspots and total_file_changes > 0:
        top_10_pct_count = max(1, len(all_files) // 10)
        top_changes = sum(h["changes"] for h in hotspots[:top_10_pct_count])
        hotspot_concentration = round(top_changes / total_file_changes, 2)
    else:
        hotspot_concentration = 0.0

    # Overall churn rate
    churn_rate = round(total_file_changes / max(total_days, 1) / max(len(all_files), 1), 2)

    return {
        "churn_rate": churn_rate,
        "hotspot_concentration": hotspot_concentration,
        "test_to_prod_ratio": test_ratio,
        "refactor_frequency": refactor_freq,
        "total_files_changed": len(all_files),
        "total_commits": total_commits,
        "commit_type_distribution": dict(sorted(type_counts.items(), key=lambda x: -x[1])),
    }


# --- Refactoring Candidates ---

def identify_refactoring_candidates(hotspots: list[dict], health: dict) -> list[dict]:
    """Identify files that are strong candidates for refactoring."""
    candidates = []
    for h in hotspots:
        reasons = []

        if h["churn_rate"] > 0.5:
            reasons.append(f"high churn rate ({h['churn_rate']}/day)")
        if h["author_count"] >= 3:
            reasons.append(f"touched by {h['author_count']} authors (coordination overhead)")
        if h["loc_churn"] > 500:
            reasons.append(f"high LOC churn ({h['loc_churn']} lines)")
        if h["changes"] >= 8:
            reasons.append(f"changed {h['changes']} times (instability)")

        if len(reasons) >= 2:
            candidates.append({
                "file": h["file"],
                "churn_score": h["churn_score"],
                "reasons": reasons,
                "recommendation": "Consider splitting, refactoring, or stabilizing this file.",
            })

    return candidates


# --- Main Analysis ---

def analyze_churn(since: str, until: str, repo: str,
                  path_filter: str | None = None,
                  top_n: int = 15,
                  oscillation: bool = False) -> dict:
    """Run full churn analysis."""
    commits = get_file_changes(since, until, repo, path_filter)

    try:
        d_since = datetime.strptime(since, "%Y-%m-%d")
        d_until = datetime.strptime(until, "%Y-%m-%d")
        total_days = max((d_until - d_since).days, 1)
    except ValueError:
        total_days = 7

    hotspots = compute_hotspots(commits, total_days, top_n)
    dir_churn = compute_directory_churn(commits)
    health = compute_health_indicators(commits, hotspots, total_days)
    candidates = identify_refactoring_candidates(hotspots, health)

    result = {
        "period": {"since": since, "until": until, "days": total_days},
        "hotspots": hotspots,
        "directory_churn": dir_churn,
        "health_indicators": health,
        "refactoring_candidates": candidates,
    }

    if oscillation:
        osc = detect_oscillation(commits)
        result["oscillation"] = osc
        # Add oscillation score to health
        total_files = health["total_files_changed"]
        osc_pct = round(len(osc) / max(total_files, 1) * 100, 1)
        result["health_indicators"]["oscillation_pct"] = osc_pct

    return result


# --- Text Formatting ---

def bar_chart(value: float, max_value: float, width: int = 20) -> str:
    if max_value == 0:
        return " " * width
    filled = min(round((value / max_value) * width), width)
    return "\u2588" * filled + "\u2591" * (width - filled)


def status_indicator(value: float, good_max: float, warn_max: float) -> str:
    if value <= good_max:
        return "OK"
    elif value <= warn_max:
        return "WARN"
    else:
        return "HIGH"


def format_text(data: dict) -> str:
    p = data["period"]
    lines = [
        f"Code Churn Analysis ({p['since']} to {p['until']})",
        "=" * 65,
        "",
    ]

    # Health indicators
    h = data["health_indicators"]
    lines.append("Health Indicators")
    lines.append("-" * 40)
    lines.append(f"  Churn Rate:            {h['churn_rate']:<8} [{status_indicator(h['churn_rate'], 0.3, 0.5)}]")
    lines.append(f"  Hotspot Concentration: {h['hotspot_concentration']:<8} [{status_indicator(h['hotspot_concentration'], 0.3, 0.5)}]")
    lines.append(f"  Test-to-Prod Ratio:    {h['test_to_prod_ratio']:<8} [{'OK' if h['test_to_prod_ratio'] >= 0.3 else 'LOW'}]")
    lines.append(f"  Refactor Frequency:    {h['refactor_frequency']:<8} [{'OK' if 0.08 <= h['refactor_frequency'] <= 0.3 else 'CHECK'}]")
    if "oscillation_pct" in h:
        lines.append(f"  Oscillation:           {h['oscillation_pct']}%    [{status_indicator(h['oscillation_pct'], 3, 8)}]")
    lines.append(f"  Total Files Changed:   {h['total_files_changed']}")
    lines.append(f"  Total Commits:         {h['total_commits']}")
    lines.append("")

    # Hotspots
    hotspots = data["hotspots"]
    if hotspots:
        max_score = hotspots[0]["churn_score"] if hotspots else 1
        lines.append("File Hotspots (ranked by churn score)")
        lines.append("-" * 65)
        lines.append(f"  {'File':<40} {'Chg':>4} {'Auth':>4} {'Score':>6}")
        lines.append(f"  {'':->40} {'':->4} {'':->4} {'':->6}")
        for h in hotspots:
            name = h["file"]
            if len(name) > 38:
                name = "..." + name[-35:]
            chart = bar_chart(h["churn_score"], max_score, 10)
            lines.append(f"  {name:<40} {h['changes']:>4} {h['author_count']:>4} {h['churn_score']:>6} {chart}")
        lines.append("")

    # Directory churn
    dir_churn = data["directory_churn"]
    if dir_churn:
        lines.append("Directory Churn")
        lines.append("-" * 50)
        max_dc = dir_churn[0]["changes"] if dir_churn else 1
        for d in dir_churn[:10]:
            chart = bar_chart(d["changes"], max_dc, 15)
            lines.append(f"  {d['directory'] + '/':<25} {d['changes']:>5} changes  {d['unique_files']:>3} files  {chart}")
        lines.append("")

    # Refactoring candidates
    candidates = data.get("refactoring_candidates", [])
    if candidates:
        lines.append("Refactoring Candidates")
        lines.append("-" * 50)
        for c in candidates:
            lines.append(f"  {c['file']}")
            for r in c["reasons"]:
                lines.append(f"    - {r}")
            lines.append(f"    >> {c['recommendation']}")
            lines.append("")

    # Oscillation
    osc = data.get("oscillation", [])
    if osc:
        lines.append("Oscillating Files (add/remove churn)")
        lines.append("-" * 50)
        for o in osc[:10]:
            lines.append(f"  {o['file']}")
            lines.append(f"    Changes: {o['total_changes']}, Direction switches: {o['direction_changes']}, Ratio: {o['oscillation_ratio']}")
        lines.append("")

    return "\n".join(lines)


# --- CLI ---

def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(
        description="Code Churn Analyzer — hotspots, oscillation, and refactoring candidates"
    )
    parser.add_argument("--days", type=int, default=7,
                        help="Number of days to analyze (default: 7)")
    parser.add_argument("--since", type=str, default=None,
                        help="Start date (YYYY-MM-DD)")
    parser.add_argument("--until", type=str, default=None,
                        help="End date (YYYY-MM-DD)")
    parser.add_argument("--top", type=int, default=15,
                        help="Number of top hotspots to show (default: 15)")
    parser.add_argument("--path", type=str, default=None,
                        help="Filter to files under this path prefix")
    parser.add_argument("--detect-oscillation", action="store_true",
                        help="Detect files with add/remove oscillation patterns")
    parser.add_argument("--repo", type=str, default=".",
                        help="Path to git repository")
    parser.add_argument("-f", "--format", choices=["text", "json"], default="text",
                        help="Output format (default: text)")
    return parser.parse_args()


def main():
    args = parse_args()

    if args.until:
        until_date = args.until
    else:
        until_date = datetime.now().strftime("%Y-%m-%d")

    if args.since:
        since_date = args.since
    else:
        d_until = datetime.strptime(until_date, "%Y-%m-%d")
        d_since = d_until - timedelta(days=args.days)
        since_date = d_since.strftime("%Y-%m-%d")

    check = run_git(["rev-parse", "--is-inside-work-tree"], args.repo)
    if check != "true":
        print(f"Error: '{args.repo}' is not a git repository.", file=sys.stderr)
        sys.exit(1)

    data = analyze_churn(
        since_date, until_date, args.repo,
        path_filter=args.path,
        top_n=args.top,
        oscillation=args.detect_oscillation,
    )

    if args.format == "json":
        print(json.dumps(data, indent=2, default=str))
    else:
        print(format_text(data))


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
Contributor Insights Analyzer

Per-contributor breakdown of commits, LOC, work patterns, specialization
detection, session analysis, and collaboration metrics from git history.

Usage:
    python contributor_insights.py --days 14
    python contributor_insights.py --days 14 --author "jane@example.com"
    python contributor_insights.py --days 14 --collaboration --format json

Standard library only.
"""

import argparse
import json
import subprocess
import sys
from collections import defaultdict
from datetime import datetime, timedelta
from typing import Any


# --- Git Helpers ---

def run_git(args: list[str], repo: str = ".") -> str:
    cmd = ["git", "-C", repo] + args
    result = subprocess.run(cmd, capture_output=True, text=True, timeout=60)
    if result.returncode != 0:
        return ""
    return result.stdout.strip()


def parse_datetime(iso_str: str) -> datetime:
    clean = iso_str.strip()
    if len(clean) > 19 and (clean[-3] == ":" and (clean[-6] == "+" or clean[-6] == "-")):
        clean = clean[:-3] + clean[-2:]
    try:
        return datetime.strptime(clean, "%Y-%m-%dT%H:%M:%S%z")
    except ValueError:
        try:
            return datetime.strptime(clean[:19], "%Y-%m-%dT%H:%M:%S")
        except ValueError:
            return datetime.now()


# --- Data Collection ---

def get_commits_with_files(since: str, until: str, repo: str = ".") -> list[dict]:
    """Get commits with file-level numstat data."""
    log = run_git([
        "log", "--all", f"--since={since}", f"--until={until}",
        "--pretty=format:COMMIT|%H|%ae|%aI|%s", "--numstat", "--no-merges"
    ], repo)
    if not log:
        return []

    commits = []
    current = None

    for line in log.split("\n"):
        line = line.strip()
        if not line:
            continue
        if line.startswith("COMMIT|"):
            if current:
                commits.append(current)
            parts = line.split("|", 4)
            if len(parts) < 5:
                current = None
                continue
            current = {
                "hash": parts[1],
                "author": parts[2],
                "date": parts[3],
                "subject": parts[4],
                "files": [],
            }
        elif current and "\t" in line:
            parts = line.split("\t")
            if len(parts) >= 3:
                try:
                    added = int(parts[0]) if parts[0] != "-" else 0
                    removed = int(parts[1]) if parts[1] != "-" else 0
                except ValueError:
                    added = 0
                    removed = 0
                current["files"].append({
                    "path": parts[2],
                    "added": added,
                    "removed": removed,
                })

    if current:
        commits.append(current)

    return commits


def get_coauthor_info(since: str, until: str, repo: str = ".") -> list[dict]:
    """Get commits with co-author trailers."""
    log = run_git([
        "log", "--all", f"--since={since}", f"--until={until}",
        "--pretty=format:%H|%ae|%b", "--no-merges"
    ], repo)
    if not log:
        return []

    coauthored = []
    for line in log.split("\n"):
        if "Co-authored-by" in line or "Co-Authored-By" in line:
            parts = line.split("|", 2)
            if len(parts) >= 3:
                coauthored.append({
                    "hash": parts[0],
                    "author": parts[1],
                    "body": parts[2],
                })
    return coauthored


# --- Specialization Detection ---

SPECIALIZATION_PATTERNS = {
    "frontend": {
        "extensions": {".tsx", ".jsx", ".vue", ".svelte", ".css", ".scss", ".sass", ".less", ".html"},
        "paths": {"src/ui", "src/components", "src/pages", "frontend/", "client/", "web/"},
    },
    "backend": {
        "extensions": {".py", ".go", ".rs", ".java", ".rb", ".php", ".cs", ".scala", ".kt"},
        "paths": {"src/api", "src/server", "backend/", "server/", "api/"},
    },
    "infrastructure": {
        "extensions": {".yml", ".yaml", ".tf", ".hcl", ".toml"},
        "paths": {"terraform/", "k8s/", "kubernetes/", ".github/", "infra/", "deploy/", "ci/"},
        "filenames": {"Dockerfile", "docker-compose.yml", "Makefile", "Jenkinsfile"},
    },
    "documentation": {
        "extensions": {".md", ".rst", ".txt", ".adoc"},
        "paths": {"docs/", "documentation/", "wiki/"},
    },
    "tests": {
        "extensions": set(),
        "paths": {"test/", "tests/", "__tests__/", "spec/", "e2e/"},
        "patterns": {"test_", "_test.", ".test.", ".spec.", "_spec."},
    },
    "data": {
        "extensions": {".sql", ".json", ".csv", ".parquet"},
        "paths": {"migrations/", "data/", "seeds/", "fixtures/"},
    },
}


def detect_specialization(filepath: str) -> str:
    """Classify a file path into a specialization category."""
    fp_lower = filepath.lower()
    filename = filepath.split("/")[-1]

    # Check tests first (pattern-based, overrides extension)
    test_pats = SPECIALIZATION_PATTERNS["tests"]
    for p in test_pats.get("paths", set()):
        if p in fp_lower:
            return "tests"
    for pat in test_pats.get("patterns", set()):
        if pat in fp_lower:
            return "tests"

    # Check other categories
    for category, rules in SPECIALIZATION_PATTERNS.items():
        if category == "tests":
            continue
        # Check filenames
        for fn in rules.get("filenames", set()):
            if filename == fn:
                return category
        # Check paths
        for path in rules.get("paths", set()):
            if path in fp_lower:
                return category
        # Check extensions
        for ext in rules.get("extensions", set()):
            if fp_lower.endswith(ext):
                return category

    return "other"


# --- Session Detection ---

def detect_sessions(timestamps: list[datetime], gap_minutes: int = 45) -> dict:
    """Detect work sessions from sorted timestamps."""
    if not timestamps:
        return {"deep_work": 0, "focused": 0, "micro": 0, "total": 0, "details": []}

    timestamps.sort()
    gap = timedelta(minutes=gap_minutes)
    sessions = []
    start = timestamps[0]
    end = timestamps[0]

    for i in range(1, len(timestamps)):
        if timestamps[i] - end > gap:
            sessions.append((start, end))
            start = timestamps[i]
            end = timestamps[i]
        else:
            end = timestamps[i]
    sessions.append((start, end))

    result = {"deep_work": 0, "focused": 0, "micro": 0, "total": len(sessions), "details": []}
    for s, e in sessions:
        dur = (e - s).total_seconds() / 60
        if dur > 50:
            stype = "deep_work"
        elif dur >= 20:
            stype = "focused"
        else:
            stype = "micro"
        result[stype] += 1
        result["details"].append({
            "start": s.isoformat(),
            "end": e.isoformat(),
            "duration_min": round(dur, 1),
            "type": stype,
        })

    return result


# --- Consistency Score ---

def compute_consistency(commit_dates: list[datetime], total_days: int) -> float:
    """Compute consistency score (0-1). Higher = more evenly distributed commits across days."""
    if not commit_dates or total_days <= 0:
        return 0.0

    day_counts = defaultdict(int)
    for dt in commit_dates:
        day_key = dt.strftime("%Y-%m-%d")
        day_counts[day_key] += 1

    active_days = len(day_counts)
    if total_days <= 1:
        return 1.0 if active_days > 0 else 0.0

    # Ratio of active days to total days, weighted by evenness
    coverage = active_days / total_days
    if active_days <= 1:
        return coverage * 0.5

    # Coefficient of variation of daily commit counts (lower = more even)
    counts = list(day_counts.values())
    mean_c = sum(counts) / len(counts)
    variance = sum((c - mean_c) ** 2 for c in counts) / len(counts)
    std_c = variance ** 0.5
    cv = std_c / mean_c if mean_c > 0 else 0

    evenness = max(0, 1 - cv)  # CV of 0 = perfectly even
    return round(coverage * 0.6 + evenness * 0.4, 2)


# --- Collaboration Metrics ---

def compute_collaboration(commits: list[dict]) -> dict:
    """Compute collaboration metrics from commit data."""
    # Files touched by each author
    author_files = defaultdict(set)
    # Directories touched by each author
    author_dirs = defaultdict(set)
    # All files and their authors
    file_authors = defaultdict(set)

    for c in commits:
        author = c["author"]
        for f in c.get("files", []):
            path = f["path"]
            author_files[author].add(path)
            file_authors[path].add(author)
            parts = path.split("/")
            if len(parts) > 1:
                directory = "/".join(parts[:-1])
                author_dirs[author].add(directory)

    # Knowledge silos: files touched by only 1 person
    total_files = len(file_authors)
    single_owner = sum(1 for authors in file_authors.values() if len(authors) == 1)
    silo_pct = round(single_owner / total_files * 100, 1) if total_files > 0 else 0

    # Cross-directory work per author
    cross_dir = {}
    for author, dirs in author_dirs.items():
        cross_dir[author] = len(dirs)

    # Bus factor per directory
    dir_authors = defaultdict(set)
    for path, authors in file_authors.items():
        parts = path.split("/")
        if len(parts) > 1:
            directory = "/".join(parts[:-1])
            dir_authors[directory].update(authors)

    bus_factor_risks = []
    for directory, authors in dir_authors.items():
        if len(authors) == 1:
            bus_factor_risks.append({
                "directory": directory,
                "sole_author": list(authors)[0],
            })

    return {
        "total_files_touched": total_files,
        "single_owner_files": single_owner,
        "single_owner_pct": silo_pct,
        "bus_factor_risks": bus_factor_risks[:20],  # Top 20
        "author_directory_spread": cross_dir,
    }


# --- Main Analysis ---

def analyze_contributors(since: str, until: str, repo: str,
                         author_filter: str | None = None,
                         collaboration: bool = False,
                         gap_minutes: int = 45) -> dict:
    """Run full contributor analysis."""
    commits = get_commits_with_files(since, until, repo)

    try:
        d_since = datetime.strptime(since, "%Y-%m-%d")
        d_until = datetime.strptime(until, "%Y-%m-%d")
        total_days = max((d_until - d_since).days, 1)
    except ValueError:
        total_days = 7

    # Group by author
    by_author = defaultdict(list)
    for c in commits:
        by_author[c["author"]].append(c)

    if author_filter:
        filtered = {}
        for author, clist in by_author.items():
            if author_filter.lower() in author.lower():
                filtered[author] = clist
        by_author = filtered

    contributors = []
    for author, author_commits in sorted(by_author.items(), key=lambda x: -len(x[1])):
        loc_added = 0
        loc_removed = 0
        files_touched = set()
        hourly = defaultdict(int)
        spec_counts = defaultdict(int)
        timestamps = []

        for c in author_commits:
            dt = parse_datetime(c["date"])
            timestamps.append(dt)
            hourly[dt.hour] += 1
            for f in c.get("files", []):
                loc_added += f["added"]
                loc_removed += f["removed"]
                files_touched.add(f["path"])
                cat = detect_specialization(f["path"])
                spec_counts[cat] += 1

        # Specialization percentages
        total_spec = sum(spec_counts.values()) or 1
        specialization = {
            k: round(v / total_spec, 2)
            for k, v in sorted(spec_counts.items(), key=lambda x: -x[1])
        }

        # Peak hours (top 4)
        sorted_hours = sorted(hourly.items(), key=lambda x: -x[1])
        peak_hours = [h for h, _ in sorted_hours[:4]]

        # Sessions
        sessions = detect_sessions(timestamps, gap_minutes)

        # Consistency
        consistency = compute_consistency(timestamps, total_days)

        # Focus areas (top directories)
        dir_counts = defaultdict(int)
        for f_path in files_touched:
            parts = f_path.split("/")
            if len(parts) > 1:
                dir_counts[parts[0]] += 1
            else:
                dir_counts["."] += 1
        top_dirs = sorted(dir_counts.items(), key=lambda x: -x[1])[:5]

        contributors.append({
            "author": author,
            "commits": len(author_commits),
            "loc_added": loc_added,
            "loc_removed": loc_removed,
            "loc_net": loc_added - loc_removed,
            "files_touched": len(files_touched),
            "peak_hours": peak_hours,
            "hourly_distribution": dict(sorted(hourly.items())),
            "specialization": specialization,
            "sessions": {
                "deep_work": sessions["deep_work"],
                "focused": sessions["focused"],
                "micro": sessions["micro"],
                "total": sessions["total"],
            },
            "consistency_score": consistency,
            "top_directories": [{"dir": d, "files": c} for d, c in top_dirs],
        })

    result = {
        "period": {"since": since, "until": until, "days": total_days},
        "contributor_count": len(contributors),
        "contributors": contributors,
    }

    if collaboration:
        result["collaboration"] = compute_collaboration(commits)

    return result


# --- Text Formatting ---

def bar_chart(value: int, max_value: int, width: int = 20) -> str:
    if max_value == 0:
        return " " * width
    filled = min(round((value / max_value) * width), width)
    return "\u2588" * filled + "\u2591" * (width - filled)


def format_text(data: dict) -> str:
    p = data["period"]
    lines = [
        f"Contributor Insights ({p['since']} to {p['until']})",
        "=" * 60,
        f"Contributors: {data['contributor_count']}",
        "",
    ]

    for c in data["contributors"]:
        lines.append("-" * 60)
        lines.append(f"Contributor: {c['author']}")
        lines.append(f"  Commits: {c['commits']} | LOC: +{c['loc_added']:,} / -{c['loc_removed']:,} (net: {c['loc_net']:+,}) | Files: {c['files_touched']}")

        # Sessions
        s = c["sessions"]
        total_s = s["total"] or 1
        lines.append(f"  Sessions: {s['total']} (deep: {s['deep_work']}, focused: {s['focused']}, micro: {s['micro']})")

        # Peak hours
        if c["peak_hours"]:
            hours_str = ", ".join(f"{h}:00" for h in c["peak_hours"])
            lines.append(f"  Peak Hours: {hours_str}")

        # Specialization
        if c["specialization"]:
            specs = [f"{k} ({v:.0%})" for k, v in list(c["specialization"].items())[:4]]
            lines.append(f"  Specialization: {', '.join(specs)}")

        # Top directories
        if c["top_directories"]:
            dirs = [f"{d['dir']}/ ({d['files']})" for d in c["top_directories"][:3]]
            lines.append(f"  Top Directories: {', '.join(dirs)}")

        # Consistency
        lines.append(f"  Consistency: {c['consistency_score']:.2f}")

        # Hourly heatmap
        hourly = c.get("hourly_distribution", {})
        if hourly:
            max_h = max(hourly.values()) if hourly else 1
            lines.append("  Hourly Activity:")
            for hour in range(24):
                count = hourly.get(hour, 0)
                if count > 0:
                    lines.append(f"    {hour:02d}:00  {bar_chart(count, max_h, 15)}  {count}")

        lines.append("")

    # Collaboration section
    collab = data.get("collaboration")
    if collab:
        lines.append("=" * 60)
        lines.append("Collaboration Metrics")
        lines.append("-" * 40)
        lines.append(f"  Total Files Touched: {collab['total_files_touched']}")
        lines.append(f"  Single-Owner Files: {collab['single_owner_files']} ({collab['single_owner_pct']}%)")

        if collab["bus_factor_risks"]:
            lines.append(f"  Bus Factor Risks ({len(collab['bus_factor_risks'])} directories):")
            for risk in collab["bus_factor_risks"][:10]:
                lines.append(f"    {risk['directory']}/ — sole author: {risk['sole_author']}")

    return "\n".join(lines)


# --- CLI ---

def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(
        description="Contributor Insights — per-person analysis from git history"
    )
    parser.add_argument("--days", type=int, default=7,
                        help="Number of days to analyze (default: 7)")
    parser.add_argument("--since", type=str, default=None,
                        help="Start date (YYYY-MM-DD)")
    parser.add_argument("--until", type=str, default=None,
                        help="End date (YYYY-MM-DD)")
    parser.add_argument("--author", type=str, default=None,
                        help="Filter to a specific author (partial match)")
    parser.add_argument("--collaboration", action="store_true",
                        help="Include collaboration and bus factor metrics")
    parser.add_argument("--gap-minutes", type=int, default=45,
                        help="Session gap threshold in minutes (default: 45)")
    parser.add_argument("--repo", type=str, default=".",
                        help="Path to git repository")
    parser.add_argument("-f", "--format", choices=["text", "json"], default="text",
                        help="Output format (default: text)")
    return parser.parse_args()


def main():
    args = parse_args()

    if args.until:
        until_date = args.until
    else:
        until_date = datetime.now().strftime("%Y-%m-%d")

    if args.since:
        since_date = args.since
    else:
        d_until = datetime.strptime(until_date, "%Y-%m-%d")
        d_since = d_until - timedelta(days=args.days)
        since_date = d_since.strftime("%Y-%m-%d")

    check = run_git(["rev-parse", "--is-inside-work-tree"], args.repo)
    if check != "true":
        print(f"Error: '{args.repo}' is not a git repository.", file=sys.stderr)
        sys.exit(1)

    data = analyze_contributors(
        since_date, until_date, args.repo,
        author_filter=args.author,
        collaboration=args.collaboration,
        gap_minutes=args.gap_minutes,
    )

    if args.format == "json":
        print(json.dumps(data, indent=2, default=str))
    else:
        print(format_text(data))


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
Retrospective Report Generator

Takes velocity, contributor, and churn analysis data (as JSON files) and
generates a comprehensive markdown retrospective report with executive
summary, velocity dashboard, contributor spotlights, code health section,
sprint comparison, and action item tracking.

Usage:
    python retro_report_generator.py \\
        --velocity velocity.json \\
        --contributors contributors.json \\
        --churn churn.json \\
        --sprint-name "Sprint 23"

    python retro_report_generator.py \\
        -v velocity.json -c contributors.json -u churn.json \\
        --previous-retro retro_sprint_22.md \\
        --previous-velocity velocity_prev.json \\
        -s "Sprint 23" -o retro_sprint_23.md

Standard library only.
"""

import argparse
import json
import re
import sys
from datetime import datetime
from typing import Any


# --- Data Loading ---

def load_json(path: str) -> dict:
    """Load a JSON file and return the parsed data."""
    try:
        with open(path, "r", encoding="utf-8") as f:
            return json.load(f)
    except (FileNotFoundError, json.JSONDecodeError) as e:
        print(f"Warning: Could not load {path}: {e}", file=sys.stderr)
        return {}


def load_text(path: str) -> str:
    """Load a text file."""
    try:
        with open(path, "r", encoding="utf-8") as f:
            return f.read()
    except FileNotFoundError:
        return ""


# --- Previous Retro Parsing ---

def extract_action_items(retro_text: str) -> list[dict]:
    """Extract action items from a previous retrospective markdown file."""
    items = []
    for line in retro_text.split("\n"):
        line = line.strip()
        # Match markdown checkboxes: - [ ] or - [x]
        match = re.match(r"^-\s*\[([ xX])\]\s*(.+)$", line)
        if match:
            checked = match.group(1).lower() == "x"
            text = match.group(2).strip()
            # Try to extract owner and due date
            owner = ""
            due = ""
            owner_match = re.search(r"Owner:\s*(\S+)", text)
            if owner_match:
                owner = owner_match.group(1)
            due_match = re.search(r"Due:\s*(\S+)", text)
            if due_match:
                due = due_match.group(1)
            # Clean text
            clean_text = re.sub(r"\s*[-—]\s*Owner:.*$", "", text).strip()
            clean_text = re.sub(r"\s*[-—]\s*Due:.*$", "", clean_text).strip()

            items.append({
                "text": clean_text,
                "done": checked,
                "owner": owner,
                "due": due,
            })
    return items


# --- Bar Charts ---

def text_bar(value: int, max_value: int, width: int = 20) -> str:
    """Generate a unicode bar chart segment."""
    if max_value == 0:
        return " " * width
    filled = min(round((value / max_value) * width), width)
    return "\u2588" * filled + "\u2591" * (width - filled)


def md_bar(value: int, max_value: int, width: int = 15) -> str:
    """Generate a markdown-friendly bar using block chars."""
    if max_value == 0:
        return ""
    filled = min(round((value / max_value) * width), width)
    return "`" + "\u2588" * filled + "\u2591" * (width - filled) + "`"


# --- Delta Formatting ---

def fmt_delta(current: float, previous: float) -> str:
    """Format a delta between two values."""
    if previous == 0:
        return "N/A"
    pct = ((current - previous) / abs(previous)) * 100
    if pct > 0:
        return f"+{pct:.0f}%"
    elif pct < 0:
        return f"{pct:.0f}%"
    return "0%"


def delta_emoji(current: float, previous: float, higher_is_better: bool = True) -> str:
    """Return a direction indicator (no emoji, text-based)."""
    if previous == 0:
        return ""
    diff = current - previous
    if abs(diff) < 0.01:
        return "(stable)"
    if higher_is_better:
        return "(up)" if diff > 0 else "(down)"
    else:
        return "(down - good)" if diff < 0 else "(up - check)"


# --- Report Sections ---

def generate_header(sprint_name: str, velocity: dict) -> str:
    """Generate report header."""
    # Extract period from velocity data
    v = velocity.get("current", velocity)
    period = v.get("period", {})
    since = period.get("since", "unknown")
    until = period.get("until", "unknown")
    now = datetime.now().strftime("%Y-%m-%d %H:%M")

    return f"""# Sprint Retrospective — {sprint_name}

**Period:** {since} to {until}
**Generated:** {now}
**Tool:** sprint-retrospective v2.0.0

---
"""


def generate_tweetable_summary(velocity: dict, churn: dict) -> str:
    """Generate a one-line tweetable summary of the sprint."""
    v = velocity.get("current", velocity)
    total_commits = v.get("total_commits", 0)
    loc_net = v.get("loc", {}).get("net", 0)
    prs = v.get("total_merges", 0)

    # Find dominant commit type
    types = v.get("commit_types", {})
    dominant = max(types.items(), key=lambda x: x[1])[0] if types else "mixed"

    # Churn health
    health = churn.get("health_indicators", {})
    test_ratio = health.get("test_to_prod_ratio", 0)

    parts = [f"{total_commits} commits"]
    if loc_net != 0:
        parts.append(f"{loc_net:+,} LOC")
    if prs > 0:
        parts.append(f"{prs} PRs merged")

    flavor = ""
    if dominant == "feat":
        flavor = "feature-heavy sprint"
    elif dominant == "fix":
        flavor = "bug-fix focused sprint"
    elif dominant == "docs":
        flavor = "documentation-heavy sprint"
    elif dominant == "refactor":
        flavor = "refactoring sprint"
    else:
        flavor = "balanced sprint"

    if test_ratio < 0.1:
        flavor += " with low test coverage"

    summary = f"> {', '.join(parts)} — {flavor}."
    return summary + "\n"


def generate_executive_summary(velocity: dict, contributors: dict, churn: dict) -> str:
    """Generate an executive summary from the data."""
    v = velocity.get("current", velocity)
    c_data = contributors
    ch = churn

    lines = ["## Executive Summary", ""]

    # Key metrics
    total_commits = v.get("total_commits", 0)
    throughput = v.get("throughput_per_day", 0)
    prs = v.get("total_merges", 0)
    loc_net = v.get("loc", {}).get("net", 0)
    authors = v.get("author_count", 0)
    cycle_time = v.get("cycle_time_hours", 0)

    lines.append(f"This sprint delivered **{total_commits} commits** across **{authors} contributors**, "
                 f"merging **{prs} PRs** with a net change of **{loc_net:+,} lines**. "
                 f"Throughput was **{throughput} commits/day** with an average cycle time of **{cycle_time} hours**.")
    lines.append("")

    # Sessions summary
    sessions = v.get("sessions", {})
    total_sessions = sessions.get("total", 0) or 1
    deep_pct = round(sessions.get("deep_work", 0) / total_sessions * 100)
    lines.append(f"Work pattern analysis: **{deep_pct}% deep work sessions**, "
                 f"{sessions.get('focused', 0)} focused sessions, "
                 f"{sessions.get('micro', 0)} micro sessions.")
    lines.append("")

    # Code health summary
    health = ch.get("health_indicators", {})
    churn_rate = health.get("churn_rate", 0)
    test_ratio = health.get("test_to_prod_ratio", 0)
    refactor_freq = health.get("refactor_frequency", 0)

    health_notes = []
    if churn_rate > 0.5:
        health_notes.append("elevated churn rate")
    if test_ratio < 0.3:
        health_notes.append("low test-to-production ratio")
    if refactor_freq < 0.08:
        health_notes.append("low refactoring activity")
    if refactor_freq > 0.3:
        health_notes.append("high refactoring activity")

    if health_notes:
        lines.append(f"**Attention areas:** {', '.join(health_notes)}.")
    else:
        lines.append("**Code health indicators are within healthy ranges.**")
    lines.append("")

    # Comparison if available
    comparison = velocity.get("comparison")
    if comparison:
        lines.append("### Sprint-over-Sprint Comparison")
        lines.append("")
        lines.append("| Metric | Current | Previous | Delta |")
        lines.append("|--------|---------|----------|-------|")
        for label, vals in comparison.items():
            lines.append(f"| {label} | {vals['current']} | {vals['previous']} | {vals['delta']} |")
        lines.append("")

    return "\n".join(lines)


def generate_velocity_dashboard(velocity: dict) -> str:
    """Generate velocity metrics dashboard."""
    v = velocity.get("current", velocity)

    lines = ["## Velocity Dashboard", ""]

    # Core metrics table
    loc = v.get("loc", {})
    lines.append("| Metric | Value |")
    lines.append("|--------|-------|")
    lines.append(f"| Total Commits | {v.get('total_commits', 0)} |")
    lines.append(f"| LOC Added | +{loc.get('added', 0):,} |")
    lines.append(f"| LOC Removed | -{loc.get('removed', 0):,} |")
    lines.append(f"| LOC Net | {loc.get('net', 0):+,} |")
    lines.append(f"| PRs Merged | {v.get('total_merges', 0)} |")
    lines.append(f"| Avg PR Size | {v.get('avg_pr_size_loc', 0)} LOC |")
    lines.append(f"| Throughput | {v.get('throughput_per_day', 0)} commits/day |")
    lines.append(f"| Cycle Time | {v.get('cycle_time_hours', 0)} hours |")
    lines.append(f"| Deploy Frequency | {v.get('deploy_frequency_per_day', 0)}/day |")
    lines.append(f"| Unique Authors | {v.get('author_count', 0)} |")
    lines.append("")

    # Commit type breakdown
    ct = v.get("commit_types", {})
    if ct:
        total_ct = sum(ct.values()) or 1
        max_ct = max(ct.values()) if ct else 1
        lines.append("### Commit Type Distribution")
        lines.append("")
        lines.append("```")
        for ctype, count in sorted(ct.items(), key=lambda x: -x[1]):
            pct = round(count / total_ct * 100)
            bar = text_bar(count, max_ct, 20)
            lines.append(f"  {ctype:<12} {bar}  {pct:>3}%  ({count})")
        lines.append("```")
        lines.append("")

    # Hourly distribution
    hourly = v.get("hourly_distribution", {})
    if hourly:
        # Convert string keys to int if needed
        hourly_int = {int(k): v for k, v in hourly.items()}
        max_h = max(hourly_int.values()) if hourly_int else 1
        lines.append("### Hourly Activity")
        lines.append("")
        lines.append("```")
        for hour in range(24):
            count = hourly_int.get(hour, 0)
            if count > 0:
                bar = text_bar(count, max_h, 25)
                lines.append(f"  {hour:02d}:00  {bar}  {count}")
        lines.append("```")
        lines.append("")

    # Session breakdown
    s = v.get("sessions", {})
    if s:
        total_s = s.get("total", 0) or 1
        lines.append("### Work Sessions")
        lines.append("")
        lines.append("| Session Type | Count | Percentage |")
        lines.append("|-------------|-------|------------|")
        lines.append(f"| Deep Work (>50min) | {s.get('deep_work', 0)} | {round(s.get('deep_work', 0)/total_s*100)}% |")
        lines.append(f"| Focused (20-50min) | {s.get('focused', 0)} | {round(s.get('focused', 0)/total_s*100)}% |")
        lines.append(f"| Micro (<20min) | {s.get('micro', 0)} | {round(s.get('micro', 0)/total_s*100)}% |")
        lines.append(f"| **Total** | **{s.get('total', 0)}** | **100%** |")
        lines.append("")

    return "\n".join(lines)


def generate_contributor_spotlights(contributors: dict) -> str:
    """Generate per-contributor spotlight sections."""
    lines = ["## Contributor Spotlights", ""]

    contribs = contributors.get("contributors", [])
    if not contribs:
        lines.append("No contributor data available.")
        return "\n".join(lines)

    for c in contribs:
        lines.append(f"### {c['author']}")
        lines.append("")
        lines.append(f"- **Commits:** {c['commits']} | **LOC:** +{c['loc_added']:,} / -{c['loc_removed']:,} (net: {c.get('loc_net', c['loc_added'] - c['loc_removed']):+,}) | **Files:** {c['files_touched']}")

        # Sessions
        s = c.get("sessions", {})
        if s:
            lines.append(f"- **Sessions:** {s.get('total', 0)} (deep: {s.get('deep_work', 0)}, focused: {s.get('focused', 0)}, micro: {s.get('micro', 0)})")

        # Peak hours
        ph = c.get("peak_hours", [])
        if ph:
            hours_str = ", ".join(f"{h}:00" for h in ph)
            lines.append(f"- **Peak Hours:** {hours_str}")

        # Specialization
        spec = c.get("specialization", {})
        if spec:
            specs = [f"{k} ({v:.0%})" for k, v in list(spec.items())[:4]]
            lines.append(f"- **Specialization:** {', '.join(specs)}")

        # Top directories
        dirs = c.get("top_directories", [])
        if dirs:
            dir_str = ", ".join(f"`{d['dir']}/` ({d['files']})" for d in dirs[:3])
            lines.append(f"- **Top Directories:** {dir_str}")

        # Consistency
        lines.append(f"- **Consistency Score:** {c.get('consistency_score', 0):.2f}")
        lines.append("")

    # Collaboration
    collab = contributors.get("collaboration")
    if collab:
        lines.append("### Collaboration Metrics")
        lines.append("")
        lines.append(f"- **Total Files Touched:** {collab['total_files_touched']}")
        lines.append(f"- **Single-Owner Files:** {collab['single_owner_files']} ({collab['single_owner_pct']}%)")

        risks = collab.get("bus_factor_risks", [])
        if risks:
            lines.append(f"- **Bus Factor Risks:** {len(risks)} directories with single owner")
            lines.append("")
            lines.append("| Directory | Sole Author |")
            lines.append("|-----------|-------------|")
            for r in risks[:10]:
                lines.append(f"| `{r['directory']}/` | {r['sole_author']} |")
            lines.append("")

    return "\n".join(lines)


def generate_code_health(churn: dict) -> str:
    """Generate code health section from churn data."""
    lines = ["## Code Health", ""]

    health = churn.get("health_indicators", {})
    if health:
        lines.append("### Health Indicators")
        lines.append("")
        lines.append("| Indicator | Value | Status |")
        lines.append("|-----------|-------|--------|")

        cr = health.get("churn_rate", 0)
        cr_status = "OK" if cr <= 0.3 else ("WARN" if cr <= 0.5 else "HIGH")
        lines.append(f"| Churn Rate | {cr} | {cr_status} |")

        hc = health.get("hotspot_concentration", 0)
        hc_status = "OK" if hc <= 0.3 else ("WARN" if hc <= 0.5 else "HIGH")
        lines.append(f"| Hotspot Concentration | {hc} | {hc_status} |")

        tr = health.get("test_to_prod_ratio", 0)
        tr_status = "OK" if tr >= 0.3 else "LOW"
        lines.append(f"| Test-to-Prod Ratio | {tr} | {tr_status} |")

        rf = health.get("refactor_frequency", 0)
        rf_status = "OK" if 0.08 <= rf <= 0.3 else "CHECK"
        lines.append(f"| Refactor Frequency | {rf} | {rf_status} |")

        if "oscillation_pct" in health:
            op = health["oscillation_pct"]
            op_status = "OK" if op <= 3 else ("WARN" if op <= 8 else "HIGH")
            lines.append(f"| Oscillation | {op}% | {op_status} |")

        lines.append("")

    # Hotspots table
    hotspots = churn.get("hotspots", [])
    if hotspots:
        lines.append("### File Hotspots")
        lines.append("")
        lines.append("| Rank | File | Changes | Authors | Churn Score |")
        lines.append("|------|------|---------|---------|-------------|")
        for i, h in enumerate(hotspots[:15], 1):
            name = h["file"]
            if len(name) > 45:
                name = "..." + name[-42:]
            lines.append(f"| {i} | `{name}` | {h['changes']} | {h['author_count']} | {h['churn_score']} |")
        lines.append("")

    # Directory churn
    dir_churn = churn.get("directory_churn", [])
    if dir_churn:
        lines.append("### Directory Activity")
        lines.append("")
        lines.append("| Directory | Changes | Files | Authors |")
        lines.append("|-----------|---------|-------|---------|")
        for d in dir_churn[:10]:
            lines.append(f"| `{d['directory']}/` | {d['changes']} | {d['unique_files']} | {d['author_count']} |")
        lines.append("")

    # Refactoring candidates
    candidates = churn.get("refactoring_candidates", [])
    if candidates:
        lines.append("### Refactoring Candidates")
        lines.append("")
        for c in candidates:
            lines.append(f"**`{c['file']}`** (score: {c['churn_score']})")
            for r in c["reasons"]:
                lines.append(f"- {r}")
            lines.append(f"- *{c['recommendation']}*")
            lines.append("")

    # Oscillation
    osc = churn.get("oscillation", [])
    if osc:
        lines.append("### Oscillating Files")
        lines.append("")
        lines.append("Files with repeated add/remove cycles, indicating possible requirement churn:")
        lines.append("")
        lines.append("| File | Changes | Direction Switches | Oscillation Ratio |")
        lines.append("|------|---------|-------------------|-------------------|")
        for o in osc[:10]:
            lines.append(f"| `{o['file']}` | {o['total_changes']} | {o['direction_changes']} | {o['oscillation_ratio']} |")
        lines.append("")

    return "\n".join(lines)


def generate_previous_items_section(items: list[dict]) -> str:
    """Generate section tracking previous action items."""
    if not items:
        return ""

    lines = ["## Previous Action Items", ""]

    done_count = sum(1 for i in items if i["done"])
    total = len(items)
    completion = round(done_count / total * 100) if total > 0 else 0

    lines.append(f"**Completion Rate:** {done_count}/{total} ({completion}%)")
    lines.append("")

    for item in items:
        check = "x" if item["done"] else " "
        text = item["text"]
        if item["owner"]:
            text += f" -- Owner: {item['owner']}"
        if item["due"]:
            text += f" -- Due: {item['due']}"
        lines.append(f"- [{check}] {text}")

    lines.append("")
    return "\n".join(lines)


def generate_action_items_section() -> str:
    """Generate empty action items section for facilitator to fill."""
    return """## New Action Items

*Fill in during the retrospective session.*

- [ ] (action item 1) -- Owner: TBD -- Due: TBD
- [ ] (action item 2) -- Owner: TBD -- Due: TBD
- [ ] (action item 3) -- Owner: TBD -- Due: TBD

"""


def generate_discussion_section() -> str:
    """Generate discussion notes section for facilitator to fill."""
    return """## Discussion Notes

### What Went Well

- (to be filled during retro)

### What Could Improve

- (to be filled during retro)

### Key Decisions

- (to be filled during retro)

"""


def generate_footer() -> str:
    return """---

*Generated by sprint-retrospective skill v2.0.0*
"""


# --- Main Report Assembly ---

def generate_report(velocity: dict, contributors: dict, churn: dict,
                    sprint_name: str, previous_retro_text: str = "",
                    previous_velocity: dict | None = None) -> str:
    """Assemble the full retrospective report."""
    sections = []

    # If velocity has comparison data, use it directly
    # If previous_velocity provided, compute comparison
    if previous_velocity and "comparison" not in velocity:
        v_current = velocity.get("current", velocity)
        v_prev = previous_velocity.get("current", previous_velocity)
        comparison = {}
        keys = [
            ("total_commits", "Commits"),
            ("total_merges", "PRs Merged"),
            ("throughput_per_day", "Throughput"),
            ("cycle_time_hours", "Cycle Time"),
            ("deploy_frequency_per_day", "Deploy Frequency"),
            ("avg_pr_size_loc", "Avg PR Size"),
        ]
        for key, label in keys:
            cur = v_current.get(key, 0)
            prev = v_prev.get(key, 0)
            comparison[label] = {
                "current": cur,
                "previous": prev,
                "delta": fmt_delta(cur, prev),
            }
        velocity = {"current": v_current, "previous": v_prev, "comparison": comparison}

    sections.append(generate_header(sprint_name, velocity))
    # Tweetable summary
    sections.append(generate_tweetable_summary(velocity, churn))
    sections.append(generate_executive_summary(velocity, contributors, churn))
    sections.append(generate_velocity_dashboard(velocity))
    sections.append(generate_contributor_spotlights(contributors))
    sections.append(generate_code_health(churn))

    # Previous action items
    if previous_retro_text:
        items = extract_action_items(previous_retro_text)
        if items:
            sections.append(generate_previous_items_section(items))

    sections.append(generate_discussion_section())
    sections.append(generate_action_items_section())
    sections.append(generate_footer())

    return "\n".join(sections)


# --- CLI ---

def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(
        description="Retrospective Report Generator — comprehensive markdown reports"
    )
    parser.add_argument("-v", "--velocity", type=str, required=True,
                        help="Path to velocity analysis JSON file")
    parser.add_argument("-c", "--contributors", type=str, default=None,
                        help="Path to contributor insights JSON file")
    parser.add_argument("-u", "--churn", type=str, default=None,
                        help="Path to code churn analysis JSON file")
    parser.add_argument("-s", "--sprint-name", type=str, default="Sprint",
                        help="Sprint name for the report title")
    parser.add_argument("--previous-retro", type=str, default=None,
                        help="Path to previous retrospective markdown (for action item tracking)")
    parser.add_argument("--previous-velocity", type=str, default=None,
                        help="Path to previous period velocity JSON (for comparison)")
    parser.add_argument("-o", "--output", type=str, default=None,
                        help="Output file path (default: stdout)")
    parser.add_argument("--save", type=str, default=None,
                        help="Save sprint snapshot to directory (e.g., .retro-history/)")
    return parser.parse_args()


def main():
    args = parse_args()

    velocity = load_json(args.velocity)
    contributors = load_json(args.contributors) if args.contributors else {}
    churn = load_json(args.churn) if args.churn else {}

    previous_retro_text = ""
    if args.previous_retro:
        previous_retro_text = load_text(args.previous_retro)

    previous_velocity = None
    if args.previous_velocity:
        previous_velocity = load_json(args.previous_velocity)

    report = generate_report(
        velocity, contributors, churn,
        sprint_name=args.sprint_name,
        previous_retro_text=previous_retro_text,
        previous_velocity=previous_velocity,
    )

    if args.output:
        with open(args.output, "w", encoding="utf-8") as f:
            f.write(report)
        print(f"Report written to {args.output}", file=sys.stderr)
    else:
        print(report)

    # Word count
    word_count = len(report.split())
    print(f"\n[Word count: {word_count}]", file=sys.stderr)

    # Save snapshot if requested
    if args.save:
        from pathlib import Path
        save_dir = Path(args.save)
        save_dir.mkdir(parents=True, exist_ok=True)
        slug = args.sprint_name.lower().replace(" ", "-")
        # Save velocity, contributors, churn snapshots
        for name, data in [("velocity", velocity), ("contributors", contributors), ("churn", churn)]:
            path = save_dir / f"{slug}-{name}.json"
            with open(path, "w", encoding="utf-8") as f:
                json.dump(data, f, indent=2)
        # Save report markdown
        report_path = save_dir / f"{slug}-report.md"
        with open(report_path, "w", encoding="utf-8") as f:
            f.write(report)
        print(f"Sprint snapshot saved to {save_dir}/{slug}-*.json", file=sys.stderr)


if __name__ == "__main__":
    main()