Github Traffic

#!/usr/bin/env python3
"""
Fetch and visualize GitHub repository traffic data.

Collects views, clones, referrers, and popular paths from the GitHub API,
stores historical data in a local JSON file, and generates trend charts
using matplotlib (ASCII fallback if matplotlib is unavailable).

Prerequisites:
  - gh CLI (authenticated with repo push access)
  - matplotlib (optional, for PNG chart generation)

Usage:
    # Fetch and display current traffic
    python github_traffic.py zilliztech/memsearch

    # Fetch, store history, and generate charts
    python github_traffic.py zilliztech/memsearch --chart

    # Generate chart for last 7 days
    python github_traffic.py zilliztech/memsearch --chart --days 7

    # Generate chart for last 90 days (requires stored history)
    python github_traffic.py zilliztech/memsearch --chart --days 90

    # Custom history file location
    python github_traffic.py zilliztech/memsearch --chart --history-dir ./data

    # Snapshot only: fetch and store data without display
    python github_traffic.py zilliztech/memsearch --snapshot
"""

from __future__ import annotations

import argparse
import json
import os
import subprocess
import sys
from datetime import datetime, timezone
from pathlib import Path


def gh_api(endpoint: str) -> dict | list:
    """Call GitHub API via gh CLI and return parsed JSON."""
    result = subprocess.run(
        ["gh", "api", endpoint],
        capture_output=True,
        text=True,
    )
    if result.returncode != 0:
        error_msg = result.stderr.strip()
        if "Must have push access" in error_msg or "403" in error_msg:
            print(f"Error: insufficient permissions for {endpoint}")
            print("Traffic data requires push (write) access to the repository.")
            print("Make sure your `gh` CLI is authenticated with a token that has repo write access.")
            sys.exit(1)
        raise RuntimeError(f"gh api failed: {error_msg}")
    return json.loads(result.stdout)


def fetch_traffic(repo: str) -> dict:
    """Fetch all traffic data for a repository."""
    views = gh_api(f"repos/{repo}/traffic/views")
    clones = gh_api(f"repos/{repo}/traffic/clones")
    referrers = gh_api(f"repos/{repo}/traffic/popular/referrers")
    paths = gh_api(f"repos/{repo}/traffic/popular/paths")
    stats = gh_api(f"repos/{repo}")

    return {
        "fetched_at": datetime.now(timezone.utc).isoformat(),
        "repo": repo,
        "stars": stats.get("stargazers_count", 0),
        "forks": stats.get("forks_count", 0),
        "open_issues": stats.get("open_issues_count", 0),
        "views": {
            "total": views.get("count", 0),
            "unique": views.get("uniques", 0),
            "daily": [
                {
                    "date": v["timestamp"][:10],
                    "views": v["count"],
                    "unique": v["uniques"],
                }
                for v in views.get("views", [])
            ],
        },
        "clones": {
            "total": clones.get("count", 0),
            "unique": clones.get("uniques", 0),
            "daily": [
                {
                    "date": c["timestamp"][:10],
                    "clones": c["count"],
                    "unique": c["uniques"],
                }
                for c in clones.get("clones", [])
            ],
        },
        "referrers": [
            {"referrer": r["referrer"], "views": r["count"], "unique": r["uniques"]}
            for r in referrers
        ],
        "paths": [
            {"path": p["path"], "views": p["count"], "unique": p["uniques"]}
            for p in paths
        ],
    }


# ---------------------------------------------------------------------------
# History persistence
# ---------------------------------------------------------------------------

def _history_file(repo: str, history_dir: str) -> Path:
    """Return the path to the history JSON file for a repo."""
    safe_name = repo.replace("/", "_")
    retur