github-rep 0.1.0__tar.gz → 0.2.0__tar.gz

github_rep-0.2.0/PKG-INFO

@@ -0,0 +1,245 @@
+Metadata-Version: 2.4
+Name: github-rep
+Version: 0.2.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-rep
+Project-URL: Bug Tracker, https://github.com/basilalshukaili/github-rep/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-rep
+
+[![PyPI version](https://img.shields.io/pypi/v/github-rep.svg)](https://pypi.org/project/github-rep/)
+[![Python versions](https://img.shields.io/pypi/pyversions/github-rep.svg)](https://pypi.org/project/github-rep/)
+[![CI](https://github.com/basilalshukaili/github-rep/actions/workflows/ci.yml/badge.svg)](https://github.com/basilalshukaili/github-rep/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+**Score any GitHub user's reputation across 11 honest signals and get a prioritized fix list — in under 30 seconds.**
+
+---
+
+## Why this exists
+
+GitHub profiles are the de-facto developer resume. Most advice on building GitHub reputation is either
+vague ("just contribute more") or gameable (spam-stars, low-effort PRs). This tool measures the signals
+that actually matter to recruiters, maintainers, and other developers — and tells you exactly what to
+fix first, ordered by impact.
+
+---
+
+## Install
+
+```bash
+pip install github-rep
+```
+
+Requires Python 3.9+. No configuration needed — works unauthenticated (60 req/hr) or with a GitHub
+token for 5000 req/hr.
+
+---
+
+## Quickstart
+
+```bash
+# Analyze any GitHub user
+github-rep analyze-profile torvalds
+
+# Use a token to avoid rate limits
+export GITHUB_TOKEN=ghp_yourtoken
+github-rep analyze-profile sindresorhus
+
+# Machine-readable JSON output
+github-rep analyze-profile gvanrossum --json
+
+# Show all findings, including low-priority ones
+github-rep analyze-profile octocat --verbose
+
+# Compare multiple profiles side by side
+github-rep compare torvalds gvanrossum sindresorhus
+
+# Check your API rate limit
+github-rep rate-limit
+```
+
+---
+
+## Sample output
+
+```
+$ github-rep analyze-profile torvalds
+
+╭──────────────────────────────── GitHub Profile ─────────────────────────────╮
+│ @torvalds  |  Linus Torvalds                                                │
+│                                                                              │
+│ Followers: 305,509  |  Public repos: 12  |  Stars earned: 246,028           │
+╰──────────────────────────────────────────────────────────────────────────────╯
+Grade: B  (78/100)
+Tier: Active developer
+
+                Score Breakdown
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━┓
+┃ Dimension                ┃  Score ┃   Max ┃
+┡━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━┩
+│ Profile Completeness     │      4 │    10 │
+│ Readme Quality           │     12 │    15 │
+│ Star Signal              │     20 │    20 │
+│ Contribution Streak      │     15 │    15 │
+│ Repo Diversity           │      7 │    10 │
+│ Description Quality      │     10 │    10 │
+│ Topic Tags               │      0 │     5 │
+│ Fork Ratio               │      5 │     5 │
+│ Recent Activity          │      5 │    10 │
+│ Release Cadence          │      0 │     5 │
+│ Profile Readme           │      0 │     5 │
+└──────────────────────────┴────────┴───────┘
+
+Priority fixes:
+  [HIGH] Missing bio
+     Your bio is empty. It is the first thing visitors read.
+     Fix: Write 1-2 sentences: your focus, what you build, your superpower.
+
+What is working:
+  [GOOD] Strong star signal (246028 total, top repo: 235147)
+  [GOOD] Active recent commits (0d ago)
+  [GOOD] All repos have descriptions
+```
+
+Grades: **A** (≥80) · **B** (≥65) · **C** (≥50) · **D** (≥35) · **F**
+
+---
+
+## The 11 scored dimensions
+
+| # | Dimension | Max pts | What it measures |
+|---|-----------|--------:|------------------|
+| 1 | Profile Completeness | 10 | Name, bio, avatar, location, website / social link |
+| 2 | README Quality | 15 | Top repo README length, code examples, install instructions |
+| 3 | Star Signal | 20 | Total stars earned across all repos (log-scaled) |
+| 4 | Contribution Streak | 15 | Days since last profile activity |
+| 5 | Repo Diversity | 10 | Number of public repos and language breadth |
+| 6 | Description Quality | 10 | Fraction of repos with meaningful descriptions |
+| 7 | Topic Tags | 5 | Repos tagged with relevant GitHub topics |
+| 8 | Fork Ratio | 5 | Proportion of original work vs. forked repos |
+| 9 | Recent Activity | 10 | Repos with pushes in the last 90 days |
+| 10 | **Release Cadence** | 5 | Published GitHub Releases on top repos |
+| 11 | **Profile README** | 5 | Presence and quality of the username/username profile README |
+
+**Total: 100 points.**
+
+Dimensions 10 and 11 are new in v0.2.0 and measure signals that indicate a polished,
+production-ready presence — publishing versioned releases and curating a profile page.
+
+---
+
+## All flags
+
+```
+github-rep analyze-profile <username> [OPTIONS]
+```
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Machine-readable JSON output (all scores + findings) |
+| `--verbose` / `-v` | Show all findings including low-priority improvements |
+| `--token` / `-t` | GitHub PAT (also reads `GITHUB_TOKEN` env var) |
+| `--top N` | Number of top repos to deep-analyze (default: 10) |
+| `--help` | Show help and exit |
+
+---
+
+## JSON output
+
+```bash
+github-rep analyze-profile gvanrossum --json
+```
+
+```json
+{
+  "username": "gvanrossum",
+  "total": 72,
+  "grade": "B",
+  "tier": "Active developer",
+  "breakdown": {
+    "profile_completeness": 8,
+    "readme_quality": 12,
+    ...
+  },
+  "findings": [
+    {
+      "category": "topic_tags",
+      "severity": "medium",
+      "title": "Most repos have no topic tags",
+      "detail": "Missing from GitHub Explore category pages entirely.",
+      "fix": "Add topics to your top 3 repos today - GitHub UI, takes 2 minutes."
+    }
+  ]
+}
+```
+
+---
+
+## Caching
+
+Results are cached for 5 minutes under `~/.cache/github-rep/` to avoid hitting rate limits when
+running the tool multiple times. Delete the cache directory to force a fresh fetch.
+
+---
+
+## FAQ
+
+**Do I need a GitHub token?**
+No. Unauthenticated usage gets 60 API requests per hour — enough for a single profile analysis.
+Set `GITHUB_TOKEN` to get 5000 requests per hour and avoid hitting limits when comparing many profiles.
+
+**How is the score calculated?**
+Each dimension is scored independently against fixed max points (totalling 100). There is no
+machine learning or relative ranking — the score reflects the absolute presence or absence of
+each signal.
+
+**Can I game the score?**
+You could game every individual metric, but you would also genuinely improve your GitHub presence
+in the process. The signals are chosen because they correlate with real reputation value.
+
+**Why does a well-known developer score lower than expected?**
+Some high-reputation developers (including Linus Torvalds) score below 80 because they skip
+signals like topic tags, profile READMEs, or GitHub Releases. The tool measures profile
+hygiene signals, not absolute influence.
+
+**How often should I re-run this?**
+After each batch of improvements. Treat it like `npm audit` — run it, fix the findings, move on.
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Bug reports and improvements welcome — open an issue on
+[github.com/basilalshukaili/github-rep](https://github.com/basilalshukaili/github-rep/issues).
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

github_rep-0.2.0/README.md

@@ -0,0 +1,213 @@
+# github-rep
+
+[![PyPI version](https://img.shields.io/pypi/v/github-rep.svg)](https://pypi.org/project/github-rep/)
+[![Python versions](https://img.shields.io/pypi/pyversions/github-rep.svg)](https://pypi.org/project/github-rep/)
+[![CI](https://github.com/basilalshukaili/github-rep/actions/workflows/ci.yml/badge.svg)](https://github.com/basilalshukaili/github-rep/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+**Score any GitHub user's reputation across 11 honest signals and get a prioritized fix list — in under 30 seconds.**
+
+---
+
+## Why this exists
+
+GitHub profiles are the de-facto developer resume. Most advice on building GitHub reputation is either
+vague ("just contribute more") or gameable (spam-stars, low-effort PRs). This tool measures the signals
+that actually matter to recruiters, maintainers, and other developers — and tells you exactly what to
+fix first, ordered by impact.
+
+---
+
+## Install
+
+```bash
+pip install github-rep
+```
+
+Requires Python 3.9+. No configuration needed — works unauthenticated (60 req/hr) or with a GitHub
+token for 5000 req/hr.
+
+---
+
+## Quickstart
+
+```bash
+# Analyze any GitHub user
+github-rep analyze-profile torvalds
+
+# Use a token to avoid rate limits
+export GITHUB_TOKEN=ghp_yourtoken
+github-rep analyze-profile sindresorhus
+
+# Machine-readable JSON output
+github-rep analyze-profile gvanrossum --json
+
+# Show all findings, including low-priority ones
+github-rep analyze-profile octocat --verbose
+
+# Compare multiple profiles side by side
+github-rep compare torvalds gvanrossum sindresorhus
+
+# Check your API rate limit
+github-rep rate-limit
+```
+
+---
+
+## Sample output
+
+```
+$ github-rep analyze-profile torvalds
+
+╭──────────────────────────────── GitHub Profile ─────────────────────────────╮
+│ @torvalds  |  Linus Torvalds                                                │
+│                                                                              │
+│ Followers: 305,509  |  Public repos: 12  |  Stars earned: 246,028           │
+╰──────────────────────────────────────────────────────────────────────────────╯
+Grade: B  (78/100)
+Tier: Active developer
+
+                Score Breakdown
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━┓
+┃ Dimension                ┃  Score ┃   Max ┃
+┡━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━┩
+│ Profile Completeness     │      4 │    10 │
+│ Readme Quality           │     12 │    15 │
+│ Star Signal              │     20 │    20 │
+│ Contribution Streak      │     15 │    15 │
+│ Repo Diversity           │      7 │    10 │
+│ Description Quality      │     10 │    10 │
+│ Topic Tags               │      0 │     5 │
+│ Fork Ratio               │      5 │     5 │
+│ Recent Activity          │      5 │    10 │
+│ Release Cadence          │      0 │     5 │
+│ Profile Readme           │      0 │     5 │
+└──────────────────────────┴────────┴───────┘
+
+Priority fixes:
+  [HIGH] Missing bio
+     Your bio is empty. It is the first thing visitors read.
+     Fix: Write 1-2 sentences: your focus, what you build, your superpower.
+
+What is working:
+  [GOOD] Strong star signal (246028 total, top repo: 235147)
+  [GOOD] Active recent commits (0d ago)
+  [GOOD] All repos have descriptions
+```
+
+Grades: **A** (≥80) · **B** (≥65) · **C** (≥50) · **D** (≥35) · **F**
+
+---
+
+## The 11 scored dimensions
+
+| # | Dimension | Max pts | What it measures |
+|---|-----------|--------:|------------------|
+| 1 | Profile Completeness | 10 | Name, bio, avatar, location, website / social link |
+| 2 | README Quality | 15 | Top repo README length, code examples, install instructions |
+| 3 | Star Signal | 20 | Total stars earned across all repos (log-scaled) |
+| 4 | Contribution Streak | 15 | Days since last profile activity |
+| 5 | Repo Diversity | 10 | Number of public repos and language breadth |
+| 6 | Description Quality | 10 | Fraction of repos with meaningful descriptions |
+| 7 | Topic Tags | 5 | Repos tagged with relevant GitHub topics |
+| 8 | Fork Ratio | 5 | Proportion of original work vs. forked repos |
+| 9 | Recent Activity | 10 | Repos with pushes in the last 90 days |
+| 10 | **Release Cadence** | 5 | Published GitHub Releases on top repos |
+| 11 | **Profile README** | 5 | Presence and quality of the username/username profile README |
+
+**Total: 100 points.**
+
+Dimensions 10 and 11 are new in v0.2.0 and measure signals that indicate a polished,
+production-ready presence — publishing versioned releases and curating a profile page.
+
+---
+
+## All flags
+
+```
+github-rep analyze-profile <username> [OPTIONS]
+```
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Machine-readable JSON output (all scores + findings) |
+| `--verbose` / `-v` | Show all findings including low-priority improvements |
+| `--token` / `-t` | GitHub PAT (also reads `GITHUB_TOKEN` env var) |
+| `--top N` | Number of top repos to deep-analyze (default: 10) |
+| `--help` | Show help and exit |
+
+---
+
+## JSON output
+
+```bash
+github-rep analyze-profile gvanrossum --json
+```
+
+```json
+{
+  "username": "gvanrossum",
+  "total": 72,
+  "grade": "B",
+  "tier": "Active developer",
+  "breakdown": {
+    "profile_completeness": 8,
+    "readme_quality": 12,
+    ...
+  },
+  "findings": [
+    {
+      "category": "topic_tags",
+      "severity": "medium",
+      "title": "Most repos have no topic tags",
+      "detail": "Missing from GitHub Explore category pages entirely.",
+      "fix": "Add topics to your top 3 repos today - GitHub UI, takes 2 minutes."
+    }
+  ]
+}
+```
+
+---
+
+## Caching
+
+Results are cached for 5 minutes under `~/.cache/github-rep/` to avoid hitting rate limits when
+running the tool multiple times. Delete the cache directory to force a fresh fetch.
+
+---
+
+## FAQ
+
+**Do I need a GitHub token?**
+No. Unauthenticated usage gets 60 API requests per hour — enough for a single profile analysis.
+Set `GITHUB_TOKEN` to get 5000 requests per hour and avoid hitting limits when comparing many profiles.
+
+**How is the score calculated?**
+Each dimension is scored independently against fixed max points (totalling 100). There is no
+machine learning or relative ranking — the score reflects the absolute presence or absence of
+each signal.
+
+**Can I game the score?**
+You could game every individual metric, but you would also genuinely improve your GitHub presence
+in the process. The signals are chosen because they correlate with real reputation value.
+
+**Why does a well-known developer score lower than expected?**
+Some high-reputation developers (including Linus Torvalds) score below 80 because they skip
+signals like topic tags, profile READMEs, or GitHub Releases. The tool measures profile
+hygiene signals, not absolute influence.
+
+**How often should I re-run this?**
+After each batch of improvements. Treat it like `npm audit` — run it, fix the findings, move on.
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Bug reports and improvements welcome — open an issue on
+[github.com/basilalshukaili/github-rep](https://github.com/basilalshukaili/github-rep/issues).
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

{github_rep-0.1.0 → github_rep-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "github-rep"
-version = "0.1.0"
+version = "0.2.0"
 description = "Analyze a GitHub profile and get honest, actionable advice for building real reputation"
 readme = "README.md"
 license = { text = "MIT" }
@@ -37,8 +37,8 @@ dev = ["pytest>=7", "responses>=0.25", "pytest-cov>=4"]
 github-rep = "github_rep.cli:app"
 
 [project.urls]
-Homepage = "https://github.com/basilalshukaili/github-reputation-engine"
-"Bug Tracker" = "https://github.com/basilalshukaili/github-reputation-engine/issues"
+Homepage = "https://github.com/basilalshukaili/github-rep"
+"Bug Tracker" = "https://github.com/basilalshukaili/github-rep/issues"
 
 [tool.setuptools.packages.find]
 where = ["src"]

github_rep-0.2.0/src/github_rep/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"