github-rep 0.1.0__py3-none-any.whl

github_rep/__init__.py

@@ -0,0 +1,3 @@
+"""github-rep: honest GitHub profile analysis and reputation advice."""
+
+__version__ = "0.1.0"

github_rep/analyzer.py

@@ -0,0 +1,435 @@
+"""Profile analyzer: scores genuine reputation signals across 9 dimensions."""
+
+from __future__ import annotations
+
+import base64
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Dict, List, Optional, Tuple
+
+from .api import GitHubClient
+
+
+@dataclass
+class Finding:
+    """A single scored observation about a GitHub profile."""
+
+    category: str
+    severity: str   # "critical" | "high" | "medium" | "low" | "good"
+    title: str
+    detail: str
+    fix: Optional[str] = None
+
+    @property
+    def icon(self) -> str:
+        return {
+            "critical": "[CRITICAL]",
+            "high":     "[HIGH]",
+            "medium":   "[MEDIUM]",
+            "low":      "[LOW]",
+            "good":     "[GOOD]",
+        }.get(self.severity, "[?]")
+
+
+@dataclass
+class ProfileScore:
+    """Complete reputation analysis for one GitHub user."""
+
+    username: str
+    total: int                            # 0-100
+    breakdown: Dict[str, int] = field(default_factory=dict)
+    findings: List[Finding] = field(default_factory=list)
+    raw_user: Dict = field(default_factory=dict)
+    raw_repos: List[Dict] = field(default_factory=list)
+
+    @property
+    def grade(self) -> str:
+        if self.total >= 80:
+            return "A"
+        if self.total >= 65:
+            return "B"
+        if self.total >= 50:
+            return "C"
+        if self.total >= 35:
+            return "D"
+        return "F"
+
+    @property
+    def tier(self) -> str:
+        if self.total >= 80:
+            return "Established OSS contributor"
+        if self.total >= 65:
+            return "Active developer"
+        if self.total >= 50:
+            return "Growing presence"
+        if self.total >= 35:
+            return "Early stage"
+        return "Just starting"
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+def _days_since(dt_str: Optional[str]) -> Optional[int]:
+    if not dt_str:
+        return None
+    try:
+        dt = datetime.fromisoformat(dt_str.replace("Z", "+00:00"))
+        return (datetime.now(timezone.utc) - dt).days
+    except Exception:
+        return None
+
+
+def _readme_score(readme_text: Optional[str]) -> Tuple[int, List[Finding]]:
+    """Score README quality 0-15 and return relevant findings."""
+    findings: List[Finding] = []
+
+    if not readme_text:
+        return 0, [Finding(
+            "readme_quality", "critical",
+            "No README",
+            "Your repo has no README. This is the #1 reason developers skip a project.",
+            "Add README.md: what it does, why it matters, how to install, quick example.",
+        )]
+
+    score = 0
+    words = len(readme_text.split())
+
+    if words < 50:
+        findings.append(Finding(
+            "readme_quality", "high",
+            "README too short",
+            f"Only {words} words. A useful README is 150-500 words.",
+            "Add: what it does, installation, usage example, screenshot.",
+        ))
+        score += 3
+    elif words < 150:
+        score += 7
+        findings.append(Finding(
+            "readme_quality", "medium",
+            "README could be richer",
+            f"{words} words - decent, but consider adding usage examples.",
+            "Add a code example or screenshot to make it concrete.",
+        ))
+    else:
+        score += 12
+
+    # Code examples
+    if "```" in readme_text or "`" in readme_text:
+        score += 2
+    else:
+        findings.append(Finding(
+            "readme_quality", "medium",
+            "No code examples",
+            "README has no inline code. Show, do not just tell.",
+            "Add a quick-start code block showing the most common use case.",
+        ))
+
+    # Installation instructions
+    has_install = any(
+        kw in readme_text.lower()
+        for kw in ["install", "pip install", "npm install", "brew install", "cargo add"]
+    )
+    if has_install:
+        score += 1
+    else:
+        findings.append(Finding(
+            "readme_quality", "low",
+            "No installation instructions",
+            "How should someone install this?",
+            'Add an "## Installation" section even if it is just `pip install <name>`.',
+        ))
+
+    return min(score, 15), findings
+
+
+# ── Main analyzer ─────────────────────────────────────────────────────────────
+
+def analyze(
+    username: str,
+    token: Optional[str] = None,
+    top_n: int = 10,
+) -> ProfileScore:
+    """Fetch GitHub data and compute a ProfileScore across 9 dimensions.
+
+    Args:
+        username:  GitHub username to analyze.
+        token:     Optional GitHub personal access token (improves rate limits).
+        top_n:     Number of top repos (by stars) to deep-analyze.
+
+    Returns:
+        ProfileScore with total (0-100), breakdown, and actionable findings.
+    """
+    client = GitHubClient(token=token)
+    user = client.get_user(username)
+    repos = client.get_repos(username, include_forks=False)
+    repos_sorted = sorted(repos, key=lambda r: r.get("stargazers_count", 0), reverse=True)
+    top_repos = repos_sorted[:top_n]
+
+    breakdown: Dict[str, int] = {}
+    findings: List[Finding] = []
+
+    # ── 1. Profile completeness (10 pts) ──────────────────────────────────────
+    pc = 0
+    if user.get("bio"):
+        pc += 3
+    else:
+        findings.append(Finding(
+            "profile_completeness", "high",
+            "Missing bio",
+            "Your bio is empty. It is the first thing visitors read.",
+            "Write 1-2 sentences: your focus, what you build, your superpower.",
+        ))
+    if user.get("location"):
+        pc += 1
+    else:
+        findings.append(Finding(
+            "profile_completeness", "low",
+            "No location set",
+            "Location builds trust and helps local dev communities find you.",
+            "Add your city/country - takes 5 seconds.",
+        ))
+    if user.get("blog") or user.get("twitter_username"):
+        pc += 2
+    else:
+        findings.append(Finding(
+            "profile_completeness", "medium",
+            "No website or social link",
+            "No linked website or Twitter/X. Credibility builder.",
+            "Add your website, LinkedIn, or Twitter handle.",
+        ))
+    if user.get("company"):
+        pc += 1
+    if user.get("email"):
+        pc += 1
+    avatar = user.get("avatar_url", "")
+    if avatar and "gravatar" not in avatar:
+        pc += 2
+    else:
+        findings.append(Finding(
+            "profile_completeness", "low",
+            "Default/gravatar avatar",
+            "A real photo or custom avatar increases perceived legitimacy.",
+            "Upload a profile photo - even a simple avatar is better than the default.",
+        ))
+    breakdown["profile_completeness"] = min(pc, 10)
+
+    # ── 2. README quality (15 pts) ────────────────────────────────────────────
+    readme_text: Optional[str] = None
+    if top_repos:
+        best = top_repos[0]
+        try:
+            raw = client.get(f"/repos/{username}/{best['name']}/readme")
+            readme_text = base64.b64decode(raw["content"]).decode("utf-8", errors="replace")
+        except Exception:
+            readme_text = None
+    readme_pts, readme_findings = _readme_score(readme_text)
+    breakdown["readme_quality"] = readme_pts
+    findings.extend(readme_findings)
+
+    # ── 3. Star signal (20 pts) ───────────────────────────────────────────────
+    total_stars = sum(r.get("stargazers_count", 0) for r in repos)
+    max_stars = max((r.get("stargazers_count", 0) for r in repos), default=0)
+    if total_stars == 0:
+        star_pts = 0
+        findings.append(Finding(
+            "star_signal", "high",
+            "Zero stars across all repos",
+            "Stars are the #1 public signal of value. Zero usually means: "
+            "no promotion, poor README, or no unique value prop.",
+            "Fix the README, then share the project genuinely in ONE relevant community.",
+        ))
+    elif total_stars < 5:
+        star_pts = 4
+        findings.append(Finding(
+            "star_signal", "medium",
+            f"Low star count ({total_stars} total)",
+            "Genuine stars come from genuine visibility.",
+            "Share in community WHEN you have something useful to say "
+            "(build log, lesson learned, solved problem).",
+        ))
+    elif total_stars < 25:
+        star_pts = 10
+    elif total_stars < 100:
+        star_pts = 15
+    elif total_stars < 500:
+        star_pts = 18
+    else:
+        star_pts = 20
+        findings.append(Finding(
+            "star_signal", "good",
+            f"Strong star signal ({total_stars} total, top repo: {max_stars})",
+            "Real community traction. Keep shipping.",
+        ))
+    breakdown["star_signal"] = star_pts
+
+    # ── 4. Contribution activity (15 pts) ─────────────────────────────────────
+    days = _days_since(user.get("updated_at"))
+    if days is None or days > 180:
+        streak_pts = 0
+        findings.append(Finding(
+            "contribution_streak", "high",
+            "No recent activity (6+ months)",
+            "Stale profiles are invisible in GitHub search and Explore.",
+            "Even small commits (docs, tests, fixes) signal an active developer.",
+        ))
+    elif days > 60:
+        streak_pts = 5
+        findings.append(Finding(
+            "contribution_streak", "medium",
+            f"Low recent activity ({days} days since last update)",
+            "Aim for a few commits per month to stay visible.",
+            "Pick one project and make a small meaningful improvement weekly.",
+        ))
+    elif days > 14:
+        streak_pts = 10
+    else:
+        streak_pts = 15
+        findings.append(Finding(
+            "contribution_streak", "good",
+            f"Active recent commits ({days}d ago)",
+            "Consistent shipping builds reputation over time.",
+        ))
+    breakdown["contribution_streak"] = streak_pts
+
+    # ── 5. Repo diversity (10 pts) ────────────────────────────────────────────
+    n_repos = len(repos)
+    if n_repos == 0:
+        div_pts = 0
+        findings.append(Finding(
+            "repo_diversity", "critical",
+            "No public repositories",
+            "Nothing to discover, nothing to star, nothing to learn from.",
+            "Publish at least one genuine project - even a small tool that solves a real problem.",
+        ))
+    elif n_repos < 3:
+        div_pts = 3
+        findings.append(Finding(
+            "repo_diversity", "medium",
+            f"Only {n_repos} public repos",
+            "A single repo limits discovery surface. Build in public.",
+            "Start a second project - even a CLI tool, a library, or documented configs.",
+        ))
+    elif n_repos < 10:
+        div_pts = 7
+    else:
+        div_pts = 10
+        languages = {r["language"] for r in repos if r.get("language")}
+        if len(languages) >= 3:
+            findings.append(Finding(
+                "repo_diversity", "good",
+                f"{n_repos} repos across {len(languages)} languages",
+                "Healthy breadth. Visitors can see range and depth.",
+            ))
+    breakdown["repo_diversity"] = div_pts
+
+    # ── 6. Description quality (10 pts) ───────────────────────────────────────
+    repos_missing_desc = [r for r in repos if not r.get("description")]
+    if repos_missing_desc:
+        pct = len(repos_missing_desc) / max(len(repos), 1)
+        desc_pts = max(0, int(10 * (1 - pct)))
+        severity = "high" if pct > 0.5 else "medium"
+        findings.append(Finding(
+            "description_quality", severity,
+            f"{len(repos_missing_desc)}/{len(repos)} repos missing descriptions",
+            "GitHub search indexes repo descriptions as keyword signal.",
+            "Add a 1-sentence description to every public repo - takes 30 seconds each.",
+        ))
+    else:
+        desc_pts = 10
+        findings.append(Finding(
+            "description_quality", "good",
+            "All repos have descriptions",
+            "Every repo is searchable and discoverable by description keyword.",
+        ))
+    breakdown["description_quality"] = desc_pts
+
+    # ── 7. Topic tags (5 pts) ─────────────────────────────────────────────────
+    repos_without_topics = [r for r in repos if not r.get("topics")]
+    if not repos_without_topics:
+        topic_pts = 5
+        findings.append(Finding(
+            "topic_tags", "good",
+            "All repos have topic tags",
+            "Topic tags make repos discoverable via GitHub Explore.",
+        ))
+    elif len(repos_without_topics) < len(repos) / 2:
+        topic_pts = 3
+        findings.append(Finding(
+            "topic_tags", "low",
+            f"{len(repos_without_topics)} repos missing topic tags",
+            "GitHub Explore uses topics to surface repos in category feeds.",
+            "Add 3-5 relevant topics per repo (e.g. python, cli, api, automation).",
+        ))
+    else:
+        topic_pts = 0
+        findings.append(Finding(
+            "topic_tags", "medium",
+            "Most repos have no topic tags",
+            "Missing from GitHub Explore category pages entirely.",
+            "Add topics to your top 3 repos today - GitHub UI, takes 2 minutes.",
+        ))
+    breakdown["topic_tags"] = topic_pts
+
+    # ── 8. Fork ratio (5 pts) ─────────────────────────────────────────────────
+    all_repos_with_forks = client.get_repos(username, include_forks=True)
+    fork_count = sum(1 for r in all_repos_with_forks if r.get("fork"))
+    total_count = len(all_repos_with_forks)
+    fork_ratio = fork_count / total_count if total_count > 0 else 0
+    if fork_ratio > 0.7:
+        fork_pts = 1
+        findings.append(Finding(
+            "fork_ratio", "medium",
+            f"High fork ratio ({fork_ratio:.0%} forks)",
+            "Forked repos dominate your profile. Visitors see mostly borrowed code.",
+            "Consider making forked experiments private, or shipping more originals.",
+        ))
+    elif fork_ratio > 0.4:
+        fork_pts = 3
+    else:
+        fork_pts = 5
+    breakdown["fork_ratio"] = fork_pts
+
+    # ── 9. Recent activity quality (10 pts) ───────────────────────────────────
+    recently_active = [
+        r for r in repos
+        if _days_since(r.get("pushed_at")) is not None
+        and (_days_since(r.get("pushed_at")) or 999) < 90
+    ]
+    if not recently_active:
+        ra_pts = 0
+        findings.append(Finding(
+            "recent_activity", "medium",
+            "No repos active in last 90 days",
+            "Consistent activity matters for GitHub algorithm visibility.",
+            "Even docs or test additions count as activity.",
+        ))
+    elif len(recently_active) < 2:
+        ra_pts = 5
+        findings.append(Finding(
+            "recent_activity", "low",
+            "Only 1 repo active in last 90 days",
+            "Single-repo focus is fine but spread to 2-3 for visibility.",
+            "Even docs or test additions count.",
+        ))
+    else:
+        ra_pts = 10
+        findings.append(Finding(
+            "recent_activity", "good",
+            f"{len(recently_active)} repos active in last 90 days",
+            "Consistent multi-repo activity signals a serious builder.",
+        ))
+    breakdown["recent_activity"] = ra_pts
+
+    # ── Aggregate ─────────────────────────────────────────────────────────────
+    total = sum(breakdown.values())
+    severity_order = {"critical": 0, "high": 1, "medium": 2, "low": 3, "good": 4}
+    findings.sort(key=lambda f: severity_order.get(f.severity, 5))
+
+    return ProfileScore(
+        username=username,
+        total=total,
+        breakdown=breakdown,
+        findings=findings,
+        raw_user=user,
+        raw_repos=repos,
+    )

github_rep/api.py

@@ -0,0 +1,100 @@
+"""GitHub API client with rate-limit awareness and caching."""
+
+import time
+import hashlib
+import json
+import os
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+import requests
+
+GITHUB_API = "https://api.github.com"
+CACHE_DIR = Path.home() / ".cache" / "github-rep"
+
+
+class RateLimitError(Exception):
+    pass
+
+
+class GitHubClient:
+    """Thin wrapper around the GitHub REST API v3.
+
+    Supports both authenticated and unauthenticated usage.
+    Unauthenticated: 60 req/hr  |  Authenticated: 5000 req/hr
+    """
+
+    def __init__(self, token: Optional[str] = None, cache_ttl: int = 300):
+        self.token = token or os.environ.get("GITHUB_TOKEN") or os.environ.get("GITHUB_PAT")
+        self.cache_ttl = cache_ttl
+        self.session = requests.Session()
+        self.session.headers.update({
+            "Accept": "application/vnd.github.v3+json",
+            "User-Agent": "github-rep/0.1.0",
+        })
+        if self.token:
+            self.session.headers["Authorization"] = f"Bearer {self.token}"
+        CACHE_DIR.mkdir(parents=True, exist_ok=True)
+
+    def _cache_key(self, url: str, params: dict) -> Path:
+        key = hashlib.md5(f"{url}{json.dumps(params, sort_keys=True)}".encode()).hexdigest()
+        return CACHE_DIR / f"{key}.json"
+
+    def _get_cached(self, url: str, params: dict) -> Optional[Any]:
+        cache_file = self._cache_key(url, params)
+        if cache_file.exists():
+            age = time.time() - cache_file.stat().st_mtime
+            if age < self.cache_ttl:
+                return json.loads(cache_file.read_text())
+        return None
+
+    def _set_cached(self, url: str, params: dict, data: Any) -> None:
+        cache_file = self._cache_key(url, params)
+        cache_file.write_text(json.dumps(data))
+
+    def get(self, path: str, params: Optional[Dict] = None, use_cache: bool = True) -> Any:
+        params = params or {}
+        url = f"{GITHUB_API}{path}"
+        if use_cache:
+            cached = self._get_cached(url, params)
+            if cached is not None:
+                return cached
+        resp = self.session.get(url, params=params)
+        if resp.status_code == 403 and "rate limit" in resp.text.lower():
+            reset = int(resp.headers.get("X-RateLimit-Reset", 0))
+            raise RateLimitError(f"Rate limited. Resets at {time.ctime(reset)}")
+        resp.raise_for_status()
+        data = resp.json()
+        if use_cache:
+            self._set_cached(url, params, data)
+        return data
+
+    def get_user(self, username: str) -> Dict:
+        return self.get(f"/users/{username}")
+
+    def get_repos(self, username: str, include_forks: bool = False) -> List[Dict]:
+        repos = []
+        page = 1
+        while True:
+            batch = self.get(f"/users/{username}/repos",
+                             params={"per_page": 100, "page": page, "sort": "updated"})
+            if not batch:
+                break
+            repos.extend(batch)
+            if len(batch) < 100:
+                break
+            page += 1
+        if not include_forks:
+            repos = [r for r in repos if not r["fork"]]
+        return repos
+
+    def get_repo(self, owner: str, repo: str) -> Dict:
+        return self.get(f"/repos/{owner}/{repo}")
+
+    def get_contributors(self, owner: str, repo: str) -> List[Dict]:
+        try:
+            return self.get(f"/repos/{owner}/{repo}/contributors", params={"per_page": 30})
+        except Exception:
+            return []
+
+    def rate_limit_status(self) -> Dict:
+        return self.get("/rate_limit", use_cache=False)

github_rep/cli.py

@@ -0,0 +1,260 @@
+"""CLI entry point for github-rep."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from .analyzer import analyze, ProfileScore
+from .api import RateLimitError, GitHubClient
+
+app = typer.Typer(
+    name="github-rep",
+    help="Analyze a GitHub profile and get honest, actionable reputation advice.",
+    add_completion=False,
+)
+console = Console()
+
+
+def _severity_color(severity: str) -> str:
+    return {
+        "critical": "bold red",
+        "high":     "red",
+        "medium":   "yellow",
+        "low":      "blue",
+        "good":     "green",
+    }.get(severity, "white")
+
+
+def _grade_color(grade: str) -> str:
+    return {"A": "bold green", "B": "green", "C": "yellow", "D": "orange3", "F": "red"}.get(grade, "white")
+
+
+def _render_score(score: ProfileScore, verbose: bool = False) -> None:
+    """Render a ProfileScore to the terminal using Rich."""
+    grade_color = _grade_color(score.grade)
+
+    # Header panel
+    user = score.raw_user
+    header_lines = [
+        f"[bold]@{score.username}[/bold]  |  {user.get('name', '')}",
+        f"{user.get('bio', '')}",
+        f"Followers: {user.get('followers', 0)}  |  "
+        f"Public repos: {user.get('public_repos', 0)}  |  "
+        f"Stars earned: {sum(r.get('stargazers_count', 0) for r in score.raw_repos)}",
+    ]
+    console.print(Panel("\n".join(header_lines), title="GitHub Profile", border_style="blue"))
+
+    # Score summary
+    grade_text = Text(f"Grade: {score.grade}  ({score.total}/100)", style=grade_color)
+    tier_text = Text(f"Tier: {score.tier}", style="bold")
+    console.print(grade_text)
+    console.print(tier_text)
+    console.print()
+
+    # Breakdown table
+    table = Table(title="Score Breakdown", show_header=True, header_style="bold cyan")
+    table.add_column("Dimension", min_width=24)
+    table.add_column("Score", justify="right", min_width=8)
+    table.add_column("Max",   justify="right", min_width=5)
+
+    dimension_max = {
+        "profile_completeness": 10,
+        "readme_quality":       15,
+        "star_signal":          20,
+        "contribution_streak":  15,
+        "repo_diversity":       10,
+        "description_quality":  10,
+        "topic_tags":            5,
+        "fork_ratio":            5,
+        "recent_activity":      10,
+    }
+
+    for dim, pts in score.breakdown.items():
+        max_pts = dimension_max.get(dim, 10)
+        bar = "█" * pts + "░" * (max_pts - pts)
+        label = dim.replace("_", " ").title()
+        color = "green" if pts >= max_pts * 0.8 else "yellow" if pts >= max_pts * 0.5 else "red"
+        table.add_row(label, f"[{color}]{pts}[/{color}]", str(max_pts))
+
+    console.print(table)
+    console.print()
+
+    # Findings
+    critical_and_high = [f for f in score.findings if f.severity in ("critical", "high")]
+    medium_and_low = [f for f in score.findings if f.severity in ("medium", "low")]
+    good = [f for f in score.findings if f.severity == "good"]
+
+    if critical_and_high:
+        console.print("[bold red]Priority fixes:[/bold red]")
+        for f in critical_and_high:
+            color = _severity_color(f.severity)
+            console.print(f"  [{color}]{f.icon} {f.title}[/{color}]")
+            console.print(f"     {f.detail}")
+            if f.fix:
+                console.print(f"     [dim]Fix: {f.fix}[/dim]")
+        console.print()
+
+    if medium_and_low and (verbose or not critical_and_high):
+        console.print("[bold yellow]Improvements:[/bold yellow]")
+        for f in medium_and_low:
+            color = _severity_color(f.severity)
+            console.print(f"  [{color}]{f.icon} {f.title}[/{color}]")
+            if verbose:
+                console.print(f"     {f.detail}")
+                if f.fix:
+                    console.print(f"     [dim]Fix: {f.fix}[/dim]")
+        console.print()
+
+    if good:
+        console.print("[bold green]What is working:[/bold green]")
+        for f in good:
+            console.print(f"  [green]{f.icon} {f.title}[/green]")
+            if verbose:
+                console.print(f"     [dim]{f.detail}[/dim]")
+        console.print()
+
+
+# ── Commands ──────────────────────────────────────────────────────────────────
+
+@app.command()
+def analyze_profile(
+    username: str = typer.Argument(..., help="GitHub username to analyze"),
+    token: Optional[str] = typer.Option(
+        None, "--token", "-t", envvar="GITHUB_TOKEN",
+        help="GitHub personal access token (optional; raises rate limit to 5000 req/hr)",
+    ),
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Show all findings including low-priority"),
+    json_output: bool = typer.Option(False, "--json", help="Output results as JSON"),
+    top_n: int = typer.Option(10, "--top", help="Number of top repos to deep-analyze"),
+) -> None:
+    """Analyze a GitHub profile and score it across 9 genuine reputation dimensions.
+
+    Examples:
+        github-rep torvalds
+        github-rep basilalshukaili --verbose
+        github-rep sindresorhus --json
+        GITHUB_TOKEN=ghp_xxx github-rep gvanrossum
+    """
+    try:
+        with console.status(f"[cyan]Analyzing @{username}...[/cyan]", spinner="dots"):
+            score = analyze(username, token=token, top_n=top_n)
+    except RateLimitError as e:
+        console.print(f"[red]Rate limit hit:[/red] {e}")
+        raise typer.Exit(1)
+    except Exception as e:
+        console.print(f"[red]Error analyzing @{username}:[/red] {e}")
+        raise typer.Exit(1)
+
+    if json_output:
+        output = {
+            "username": score.username,
+            "total": score.total,
+            "grade": score.grade,
+            "tier": score.tier,
+            "breakdown": score.breakdown,
+            "findings": [
+                {
+                    "category": f.category,
+                    "severity": f.severity,
+                    "title": f.title,
+                    "detail": f.detail,
+                    "fix": f.fix,
+                }
+                for f in score.findings
+            ],
+        }
+        console.print(json.dumps(output, indent=2))
+        return
+
+    _render_score(score, verbose=verbose)
+
+
+@app.command()
+def compare(
+    usernames: list[str] = typer.Argument(..., help="Two or more GitHub usernames to compare"),
+    token: Optional[str] = typer.Option(None, "--token", "-t", envvar="GITHUB_TOKEN"),
+) -> None:
+    """Compare two or more GitHub profiles side by side.
+
+    Example:
+        github-rep compare torvalds gvanrossum sindresorhus
+    """
+    if len(usernames) < 2:
+        console.print("[red]Provide at least 2 usernames to compare.[/red]")
+        raise typer.Exit(1)
+
+    scores = []
+    for username in usernames:
+        try:
+            with console.status(f"[cyan]Analyzing @{username}...[/cyan]", spinner="dots"):
+                scores.append(analyze(username, token=token))
+        except Exception as e:
+            console.print(f"[yellow]Skipping @{username}: {e}[/yellow]")
+
+    if not scores:
+        raise typer.Exit(1)
+
+    table = Table(title="Profile Comparison", show_header=True, header_style="bold cyan")
+    table.add_column("Dimension", min_width=24)
+    for s in scores:
+        table.add_column(f"@{s.username}", justify="right", min_width=12)
+
+    dimensions = [
+        "profile_completeness", "readme_quality", "star_signal",
+        "contribution_streak", "repo_diversity", "description_quality",
+        "topic_tags", "fork_ratio", "recent_activity",
+    ]
+    for dim in dimensions:
+        row = [dim.replace("_", " ").title()]
+        for s in scores:
+            pts = s.breakdown.get(dim, 0)
+            row.append(str(pts))
+        table.add_row(*row)
+
+    # Total row
+    totals = ["[bold]TOTAL[/bold]"]
+    for s in scores:
+        grade_color = _grade_color(s.grade)
+        totals.append(f"[{grade_color}]{s.total} ({s.grade})[/{grade_color}]")
+    table.add_row(*totals)
+
+    console.print(table)
+
+
+@app.command()
+def rate_limit(
+    token: Optional[str] = typer.Option(None, "--token", "-t", envvar="GITHUB_TOKEN"),
+) -> None:
+    """Check your current GitHub API rate limit status."""
+    client = GitHubClient(token=token)
+    try:
+        data = client.rate_limit_status()
+        core = data.get("resources", {}).get("core", {})
+        remaining = core.get("remaining", "?")
+        limit = core.get("limit", "?")
+        reset_ts = core.get("reset")
+        import time
+        reset_str = time.ctime(reset_ts) if reset_ts else "?"
+        console.print(f"[cyan]Rate limit:[/cyan] {remaining}/{limit} remaining, resets at {reset_str}")
+        if not token:
+            console.print("[yellow]Tip: set GITHUB_TOKEN to get 5000 req/hr instead of 60.[/yellow]")
+    except Exception as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1)
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

github_rep-0.1.0.dist-info/METADATA

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: github-rep
+Version: 0.1.0
+Summary: Analyze a GitHub profile and get honest, actionable advice for building real reputation
+Author-email: Basil Alshukaili <basilalshukaili@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/basilalshukaili/github-reputation-engine
+Project-URL: Bug Tracker, https://github.com/basilalshukaili/github-reputation-engine/issues
+Keywords: github,open-source,developer-tools,profile,reputation,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.9
+Requires-Dist: python-dateutil>=2.8
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: responses>=0.25; extra == "dev"
+Requires-Dist: pytest-cov>=4; extra == "dev"
+Dynamic: license-file
+
+# GitHub Reputation Engine 🛠️
+
+A self-improving "second brain" + operating system for building **genuine GitHub reputation**
+through high-quality open-source contributions — run by an AI agent (Hermes Agent or Claude Code),
+autonomously, one project at a time.
+
+**Owner:** Basil Al Shukaili ([@basilalshukaili](https://github.com/basilalshukaili))
+
+> Quality of contribution > volume. One merged, appreciated PR beats fifty rejected typo fixes.
+
+## What this repo is
+
+This repo is the **portable brain** of the operation. It lets any agent, on any laptop, continue
+the same mission with full context. It contains the plan, live state, reusable playbooks, a
+journal of work done, lessons learned, and nightly strategic "dreams."
+
+Start here → [`CLAUDE.md`](./CLAUDE.md) (operating instructions, auto-loaded by Claude Code/Hermes).
+
+## Structure
+
+```
+.
+├── CLAUDE.md            # Operating instructions — read first (works with Claude Code, Hermes, Codex…)
+├── 00-System/           # roadmap, architecture, guardrails (the constitution)
+├── 01-Targets/          # the ONE active project + next action
+├── 02-Repos/            # per-repo dossiers (stack, conventions, maintainers, opportunities)
+├── 03-Journal/          # daily log of what was attempted/done (append-only per day)
+├── 04-Playbooks/        # portable, agent-agnostic procedures (triage, PR craft, dreaming)
+├── 05-Lessons/          # mistakes & wins → rules for next time
+├── 06-Dreams/           # nightly reflective synthesis: patterns, connections, next moves
+└── 99-Inbox/            # scratch captures
+```
+
+## How it works
+
+```
+Brain (top model)  — plans, reviews every diff, writes all maintainer-facing prose, commits
+   │ delegates mechanical, fully-specified work
+Worker (mid model) — implements to spec, runs tests, triage scans
+   │
+This repo (state)  — feeds full context back to the Brain on every session
+   │
+Playbooks (procedure) + Journal/Lessons/Dreams (self-improvement loop)
+```
+
+**Token discipline without quality loss:** route cheap/mechanical work to cheaper models; keep
+all judgment and human-facing writing on the top model. No output-degrading "compression" tricks.
+
+## Multi-machine usage
+
+- **Laptop A (Hermes Agent):** runs the 24/7 cadence (cron missions + nightly dreaming),
+  reports to Telegram. Skills live in Hermes; this repo holds the portable state + playbooks.
+- **Laptop B (Claude Code):** clone this repo, open it, and Claude Code auto-reads `CLAUDE.md`.
+  The playbooks in `04-Playbooks/` are agent-agnostic, so the workflow is identical.
+
+Pull before you start, commit + push when you finish, so both machines stay in sync.
+
+## Safety
+
+- No secrets are committed (API keys / bot tokens live in each machine's local env).
+- Agents fork → branch → PR; never push to an upstream default branch.
+- Respects each project's CONTRIBUTING rules and any anti-AI-PR policies.
+
+## License
+
+MIT — see [`LICENSE`](./LICENSE).

github_rep-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+github_rep/__init__.py,sha256=6gOxIvSxNvBq3X9sE-WA2Fkw8L5RoWY67Yosalfag08,95
+github_rep/analyzer.py,sha256=VHBvSuAbRsRVrdqwaALO2splyypvWOt9C2RziNAR8fY,16813
+github_rep/api.py,sha256=IpdkoKYlg0VT2BPwsu7-60EcTJvFAGMKV_VOc1gz4ug,3559
+github_rep/cli.py,sha256=9M8cfLYtOipz7nYB6Ff8cjyFFaZaAG8Lnk4LHTOJC2k,9103
+github_rep-0.1.0.dist-info/licenses/LICENSE,sha256=7cTzO3IgdzX4tnvADOt1rZSZKc3dYWCglc_cYdhdAxY,1074
+github_rep-0.1.0.dist-info/METADATA,sha256=CJpgd-8FsK1qeI9KVuppzo-aByyHVCTHBWm3TfftXsY,4347
+github_rep-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+github_rep-0.1.0.dist-info/entry_points.txt,sha256=TFGoRTxJFP6L_Y6ZoLhXznV5MG-fqo7t15kaWVaodD0,50
+github_rep-0.1.0.dist-info/top_level.txt,sha256=GqG8Q5kiHgyUM6ru_6k69Y7YzoRriNtN7i94bs5iiBw,11
+github_rep-0.1.0.dist-info/RECORD,,

github_rep-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

github_rep-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+github-rep = github_rep.cli:app

github_rep-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Basil Al Shukaili
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

github_rep-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+github_rep