repocheck-cli 0.1.0__tar.gz

repocheck_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Syed Ahmed Ali
+
+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.

repocheck_cli-0.1.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: repocheck-cli
+Version: 0.1.0
+Summary: Scan any GitHub repo and get an instant engineering health report card.
+Author: Syed Ahmed Ali
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Ahmed0754/repocheck
+Project-URL: Repository, https://github.com/Ahmed0754/repocheck
+Project-URL: Issues, https://github.com/Ahmed0754/repocheck/issues
+Keywords: github,cli,code-quality,devtools,ci
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: requests>=2.31
+Requires-Dist: rich>=13.7
+Dynamic: license-file
+
+# repocheck
+
+Scan any public GitHub repo and get an instant engineering health report card — README quality, CI/CD, test presence, dependency hygiene, license, commit activity, and issue hygiene, scored A–F.
+
+```
+$ repocheck pallets/flask
+
+╭─ repo ──────────────────╮
+│ pallets/flask           │
+│ ★ 68234  ⑂ 16200  Python│
+╰──────────────────────────╯
+╭─ overall health score ──╮
+│ 91/100  (A)              │
+╰───────────────────────────╯
+
+Check               Score  Grade
+README Quality        100    A
+CI/CD                  90    A
+Test Presence          85    B
+Dependency Hygiene     80    B
+License               100    A
+Commit Activity        95    A
+Issue Hygiene          85    B
+```
+
+## Install
+
+```bash
+pip install repocheck-cli
+```
+
+## Usage
+
+```bash
+# owner/repo shorthand
+repocheck pallets/flask
+
+# full URL also works
+repocheck https://github.com/psf/requests
+
+# detailed reasoning behind every score
+repocheck torvalds/linux -v
+
+# machine-readable output (for CI pipelines, scripts)
+repocheck your-org/your-repo --json
+```
+
+### Higher rate limits
+
+GitHub's anonymous API limit is 60 requests/hour. `repocheck` makes ~8 requests per scan, so you'll hit that fast without auth. Set a token to bump it to 5,000/hour:
+
+```bash
+export GITHUB_TOKEN=ghp_your_token_here
+repocheck your-org/your-repo
+```
+
+No special scopes needed — a basic personal access token works fine for public repos.
+
+## What it checks
+
+| Check | What it looks at |
+|---|---|
+| **README Quality** | Presence, length, install/usage sections, badges, code blocks |
+| **CI/CD** | GitHub Actions workflows, legacy CI configs |
+| **Test Presence** | Test directories, test config files, declared test scripts |
+| **Dependency Hygiene** | Manifest presence, version pinning, lockfiles |
+| **License** | OSS license presence and type |
+| **Commit Activity** | Recency and message quality of recent commits |
+| **Issue Hygiene** | Open issue count and staleness |
+
+Each check is scored 0–100 and the overall score is an average across all seven.
+
+## Why
+
+Most "is this repo any good" judgments are vibes-based — a glance at stars, maybe the README. `repocheck` turns that into a repeatable, objective-ish checklist you can run on your own repos before sharing them, or use to quickly evaluate a dependency before adopting it.
+
+## Local development
+
+```bash
+git clone https://github.com/Ahmed0754/repocheck
+cd repocheck
+pip install -e ".[dev]"
+repocheck pallets/flask
+```
+
+## License
+
+MIT

repocheck_cli-0.1.0/README.md

@@ -0,0 +1,88 @@
+# repocheck
+
+Scan any public GitHub repo and get an instant engineering health report card — README quality, CI/CD, test presence, dependency hygiene, license, commit activity, and issue hygiene, scored A–F.
+
+```
+$ repocheck pallets/flask
+
+╭─ repo ──────────────────╮
+│ pallets/flask           │
+│ ★ 68234  ⑂ 16200  Python│
+╰──────────────────────────╯
+╭─ overall health score ──╮
+│ 91/100  (A)              │
+╰───────────────────────────╯
+
+Check               Score  Grade
+README Quality        100    A
+CI/CD                  90    A
+Test Presence          85    B
+Dependency Hygiene     80    B
+License               100    A
+Commit Activity        95    A
+Issue Hygiene          85    B
+```
+
+## Install
+
+```bash
+pip install repocheck-cli
+```
+
+## Usage
+
+```bash
+# owner/repo shorthand
+repocheck pallets/flask
+
+# full URL also works
+repocheck https://github.com/psf/requests
+
+# detailed reasoning behind every score
+repocheck torvalds/linux -v
+
+# machine-readable output (for CI pipelines, scripts)
+repocheck your-org/your-repo --json
+```
+
+### Higher rate limits
+
+GitHub's anonymous API limit is 60 requests/hour. `repocheck` makes ~8 requests per scan, so you'll hit that fast without auth. Set a token to bump it to 5,000/hour:
+
+```bash
+export GITHUB_TOKEN=ghp_your_token_here
+repocheck your-org/your-repo
+```
+
+No special scopes needed — a basic personal access token works fine for public repos.
+
+## What it checks
+
+| Check | What it looks at |
+|---|---|
+| **README Quality** | Presence, length, install/usage sections, badges, code blocks |
+| **CI/CD** | GitHub Actions workflows, legacy CI configs |
+| **Test Presence** | Test directories, test config files, declared test scripts |
+| **Dependency Hygiene** | Manifest presence, version pinning, lockfiles |
+| **License** | OSS license presence and type |
+| **Commit Activity** | Recency and message quality of recent commits |
+| **Issue Hygiene** | Open issue count and staleness |
+
+Each check is scored 0–100 and the overall score is an average across all seven.
+
+## Why
+
+Most "is this repo any good" judgments are vibes-based — a glance at stars, maybe the README. `repocheck` turns that into a repeatable, objective-ish checklist you can run on your own repos before sharing them, or use to quickly evaluate a dependency before adopting it.
+
+## Local development
+
+```bash
+git clone https://github.com/Ahmed0754/repocheck
+cd repocheck
+pip install -e ".[dev]"
+repocheck pallets/flask
+```
+
+## License
+
+MIT

repocheck_cli-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "repocheck-cli"
+version = "0.1.0"
+description = "Scan any GitHub repo and get an instant engineering health report card."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{ name = "Syed Ahmed Ali" }]
+keywords = ["github", "cli", "code-quality", "devtools", "ci"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Environment :: Console",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = [
+    "click>=8.1",
+    "requests>=2.31",
+    "rich>=13.7",
+]
+
+[project.urls]
+Homepage = "https://github.com/Ahmed0754/repocheck"
+Repository = "https://github.com/Ahmed0754/repocheck"
+Issues = "https://github.com/Ahmed0754/repocheck/issues"
+
+[project.scripts]
+repocheck = "repocheck.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["repocheck*"]

repocheck_cli-0.1.0/repocheck/__init__.py

@@ -0,0 +1,3 @@
+"""repocheck — scan a GitHub repo and get a health report card."""
+
+__version__ = "0.1.0"

repocheck_cli-0.1.0/repocheck/checks.py

@@ -0,0 +1,293 @@
+"""Individual health checks. Each returns a CheckResult with a 0-100 score."""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Callable
+
+from .github_client import GitHubClient, RepoRef
+
+DEPENDENCY_FILES = (
+    "requirements.txt",
+    "package.json",
+    "Pipfile",
+    "pyproject.toml",
+    "go.mod",
+    "Cargo.toml",
+)
+
+TEST_DIR_HINTS = ("test", "tests", "__tests__", "spec")
+TEST_CONFIG_HINTS = (
+    "pytest.ini",
+    "setup.cfg",
+    "tox.ini",
+    "jest.config.js",
+    "jest.config.ts",
+    "vitest.config.ts",
+    "phpunit.xml",
+)
+
+
+@dataclass
+class CheckResult:
+    name: str
+    score: int  # 0-100
+    grade: str
+    details: list[str] = field(default_factory=list)
+    weight: float = 1.0
+
+    @staticmethod
+    def grade_for(score: int) -> str:
+        if score >= 90:
+            return "A"
+        if score >= 80:
+            return "B"
+        if score >= 70:
+            return "C"
+        if score >= 60:
+            return "D"
+        return "F"
+
+
+def _result(name: str, score: int, details: list[str], weight: float = 1.0) -> CheckResult:
+    score = max(0, min(100, score))
+    return CheckResult(name=name, score=score, grade=CheckResult.grade_for(score), details=details, weight=weight)
+
+
+# ---------------------------------------------------------------------------
+# Individual checks
+# ---------------------------------------------------------------------------
+
+def check_readme(client: GitHubClient, ref: RepoRef) -> CheckResult:
+    files = client.root_files(ref)
+    readme_name = next((f for f in files if f.lower().startswith("readme")), None)
+
+    if not readme_name:
+        return _result("README", 0, ["No README file found at repo root."])
+
+    text = client.file_text(ref, readme_name) or ""
+    details = [f"Found {readme_name} ({len(text)} chars)."]
+    score = 30  # baseline for existing
+
+    length = len(text)
+    if length > 300:
+        score += 15
+        details.append("Has substantive content (>300 chars).")
+    else:
+        details.append("Very short — consider expanding (currently <300 chars).")
+
+    lower = text.lower()
+
+    has_install = bool(re.search(r"\b(install|pip install|npm install|getting started|setup)\b", lower))
+    if has_install:
+        score += 20
+        details.append("Includes install/setup instructions.")
+    else:
+        details.append("No clear install/setup section found.")
+
+    has_usage = bool(re.search(r"\b(usage|example|quick ?start)\b", lower))
+    if has_usage:
+        score += 20
+        details.append("Includes usage/example section.")
+    else:
+        details.append("No usage or example section found.")
+
+    has_badges = "![" in text and ("shields.io" in text or "badge" in lower)
+    if has_badges:
+        score += 10
+        details.append("Has status badges (CI, version, etc).")
+
+    has_code_block = "```" in text
+    if has_code_block:
+        score += 5
+        details.append("Contains code blocks.")
+
+    return _result("README Quality", score, details)
+
+
+def check_ci(client: GitHubClient, ref: RepoRef) -> CheckResult:
+    workflows = client.workflows(ref)
+    if workflows:
+        names = [w["name"] for w in workflows if w.get("type") == "file"]
+        return _result(
+            "CI/CD",
+            90 if len(names) >= 1 else 70,
+            [f"GitHub Actions configured ({len(names)} workflow file(s)): {', '.join(names) or 'unnamed'}."],
+        )
+
+    root_files = client.root_files(ref)
+    legacy = [f for f in root_files if f in (".travis.yml", ".circleci", "azure-pipelines.yml", ".gitlab-ci.yml")]
+    if legacy:
+        return _result("CI/CD", 60, [f"Legacy CI config found: {', '.join(legacy)}. Consider migrating to GitHub Actions."])
+
+    return _result("CI/CD", 0, ["No CI/CD configuration found (no .github/workflows, no legacy CI config)."])
+
+
+def check_tests(client: GitHubClient, ref: RepoRef) -> CheckResult:
+    dirs = [d.lower() for d in client.root_dirs(ref)]
+    files = [f.lower() for f in client.root_files(ref)]
+
+    has_test_dir = any(hint in dirs for hint in TEST_DIR_HINTS)
+    has_test_config = any(hint in files for hint in TEST_CONFIG_HINTS)
+
+    details = []
+    score = 0
+
+    if has_test_dir:
+        score += 60
+        matched = [d for d in dirs if d in TEST_DIR_HINTS]
+        details.append(f"Found test directory: {', '.join(matched)}.")
+    else:
+        details.append("No conventional test directory found (tests/, test/, __tests__/, spec/).")
+
+    if has_test_config:
+        score += 25
+        matched = [f for f in files if f in [h.lower() for h in TEST_CONFIG_HINTS]]
+        details.append(f"Found test config: {', '.join(matched)}.")
+
+    # package.json may declare a test script
+    pkg = client.file_text(ref, "package.json")
+    if pkg and '"test"' in pkg and "no test specified" not in pkg.lower():
+        score += 15
+        details.append("package.json declares a test script.")
+
+    if score == 0:
+        details.append("No evidence of automated testing.")
+
+    return _result("Test Presence", score, details)
+
+
+def check_dependencies(client: GitHubClient, ref: RepoRef) -> CheckResult:
+    files = client.root_files(ref)
+    found = [f for f in DEPENDENCY_FILES if f in files]
+
+    if not found:
+        return _result("Dependency Hygiene", 50, ["No standard dependency manifest found — may be dependency-free or non-standard layout."])
+
+    details = [f"Found manifest(s): {', '.join(found)}."]
+    score = 70  # baseline for having a manifest
+
+    # Check for pinned vs unpinned versions as a rough hygiene signal
+    if "requirements.txt" in found:
+        text = client.file_text(ref, "requirements.txt") or ""
+        lines = [l for l in text.splitlines() if l.strip() and not l.startswith("#")]
+        pinned = [l for l in lines if "==" in l]
+        if lines:
+            pin_ratio = len(pinned) / len(lines)
+            if pin_ratio > 0.7:
+                score += 15
+                details.append(f"{len(pinned)}/{len(lines)} dependencies are version-pinned.")
+            else:
+                details.append(f"Only {len(pinned)}/{len(lines)} dependencies are version-pinned — consider pinning for reproducibility.")
+
+    if "package.json" in found:
+        text = client.file_text(ref, "package.json") or ""
+        if '"dependencies"' in text or '"devDependencies"' in text:
+            score += 10
+            details.append("package.json declares dependencies.")
+        if "lock" in [f.lower() for f in files] or "package-lock.json" in files or "yarn.lock" in files:
+            score += 10
+            details.append("Lockfile present (reproducible installs).")
+        else:
+            details.append("No lockfile found (package-lock.json / yarn.lock) — installs may not be reproducible.")
+
+    return _result("Dependency Hygiene", score, details)
+
+
+def check_license(client: GitHubClient, ref: RepoRef) -> CheckResult:
+    repo_data = client.repo(ref)
+    license_info = repo_data.get("license")
+    if license_info:
+        return _result("License", 100, [f"Licensed under {license_info.get('name', license_info.get('spdx_id'))}."])
+
+    files = client.root_files(ref)
+    license_file = next((f for f in files if f.lower().startswith("license")), None)
+    if license_file:
+        return _result("License", 80, [f"License file present ({license_file}) but not detected by GitHub's API."])
+
+    return _result("License", 0, ["No license found. Repo is effectively 'all rights reserved' by default."])
+
+
+def check_activity(client: GitHubClient, ref: RepoRef) -> CheckResult:
+    commits = client.commits(ref, per_page=30)
+    if not commits:
+        return _result("Commit Activity", 0, ["No commit history accessible."])
+
+    details = []
+    score = 0
+
+    try:
+        latest_date_str = commits[0]["commit"]["committer"]["date"]
+        latest_date = datetime.fromisoformat(latest_date_str.replace("Z", "+00:00"))
+        days_since = (datetime.now(timezone.utc) - latest_date).days
+        details.append(f"Last commit {days_since} day(s) ago.")
+        if days_since <= 30:
+            score += 50
+        elif days_since <= 180:
+            score += 30
+        elif days_since <= 365:
+            score += 15
+        else:
+            details.append("Repo appears inactive (no commits in over a year).")
+    except (KeyError, ValueError):
+        pass
+
+    # Commit message quality — rough heuristic: average length, non-trivial messages
+    messages = [c["commit"]["message"].splitlines()[0] for c in commits if c.get("commit")]
+    trivial = sum(1 for m in messages if m.strip().lower() in ("fix", "update", "wip", "test", "asdf", "."))
+    avg_len = sum(len(m) for m in messages) / len(messages) if messages else 0
+
+    if avg_len >= 20:
+        score += 30
+        details.append(f"Commit messages average {avg_len:.0f} chars — reasonably descriptive.")
+    else:
+        details.append(f"Commit messages average {avg_len:.0f} chars — consider more descriptive messages.")
+
+    if trivial / max(len(messages), 1) > 0.3:
+        details.append(f"{trivial}/{len(messages)} recent commits have low-effort messages (e.g. 'fix', 'wip').")
+    else:
+        score += 20
+
+    return _result("Commit Activity", score, details)
+
+
+def check_issue_hygiene(client: GitHubClient, ref: RepoRef) -> CheckResult:
+    repo_data = client.repo(ref)
+    open_issues = repo_data.get("open_issues_count", 0)
+
+    if open_issues == 0:
+        return _result("Issue Hygiene", 100, ["No open issues — clean backlog (or issues disabled)."])
+
+    issues = client.issues(ref, state="open", per_page=50)
+    # Filter out PRs, which the issues endpoint includes
+    real_issues = [i for i in issues if "pull_request" not in i]
+
+    if not real_issues:
+        return _result("Issue Hygiene", 90, [f"{open_issues} open issue(s) reported, but none returned detail (possibly all PRs)."])
+
+    now = datetime.now(timezone.utc)
+    stale = 0
+    for issue in real_issues:
+        created = datetime.fromisoformat(issue["created_at"].replace("Z", "+00:00"))
+        if (now - created).days > 90:
+            stale += 1
+
+    stale_ratio = stale / len(real_issues)
+    score = int(100 - (stale_ratio * 80))
+    details = [
+        f"{open_issues} open issue(s) total.",
+        f"{stale}/{len(real_issues)} sampled issues are older than 90 days.",
+    ]
+    return _result("Issue Hygiene", score, details)
+
+
+CHECKS: list[Callable[[GitHubClient, RepoRef], CheckResult]] = [
+    check_readme,
+    check_ci,
+    check_tests,
+    check_dependencies,
+    check_license,
+    check_activity,
+    check_issue_hygiene,
+]

repocheck_cli-0.1.0/repocheck/cli.py

@@ -0,0 +1,114 @@
+"""repocheck CLI."""
+from __future__ import annotations
+
+import json
+import sys
+
+import click
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from .github_client import GitHubClient, GitHubError, parse_repo_arg
+from .report import run_report
+
+console = Console()
+
+GRADE_COLORS = {
+    "A": "green",
+    "B": "cyan",
+    "C": "yellow",
+    "D": "orange3",
+    "F": "red",
+}
+
+
+def _grade_text(grade: str) -> Text:
+    color = GRADE_COLORS.get(grade, "white")
+    return Text(grade, style=f"bold {color}")
+
+
+@click.command()
+@click.argument("repo")
+@click.option("--token", envvar="GITHUB_TOKEN", help="GitHub personal access token (or set GITHUB_TOKEN env var).")
+@click.option("--json", "as_json", is_flag=True, help="Output raw JSON instead of a formatted report.")
+@click.option("--verbose", "-v", is_flag=True, help="Show detailed reasoning for every check.")
+@click.version_option()
+def main(repo: str, token: str | None, as_json: bool, verbose: bool):
+    """Scan a GitHub REPO (owner/repo or URL) and print a health report card.
+
+    \b
+    Examples:
+      repocheck pallets/flask
+      repocheck https://github.com/psf/requests
+      repocheck torvalds/linux --json
+    """
+    try:
+        ref = parse_repo_arg(repo)
+    except ValueError as e:
+        console.print(f"[bold red]Error:[/bold red] {e}")
+        sys.exit(1)
+
+    client = GitHubClient(token=token)
+
+    try:
+        with console.status(f"[bold blue]Scanning {ref.full_name}..."):
+            report = run_report(client, ref)
+    except GitHubError as e:
+        console.print(f"[bold red]Error:[/bold red] {e}")
+        sys.exit(1)
+
+    if as_json:
+        print(json.dumps(report.to_dict(), indent=2))
+        return
+
+    _render(report, verbose=verbose)
+
+
+def _render(report, verbose: bool):
+    grade_color = GRADE_COLORS.get(report.overall_grade, "white")
+    header = Text()
+    header.append(f"{report.repo.full_name}\n", style="bold")
+    header.append(f"★ {report.repo_meta.get('stargazers_count', 0)}  ", style="dim")
+    header.append(f"⑂ {report.repo_meta.get('forks_count', 0)}  ", style="dim")
+    header.append(f"{report.repo_meta.get('language') or 'unknown'}", style="dim")
+
+    score_text = Text()
+    score_text.append(f"{report.overall_score}/100  ", style=f"bold {grade_color}")
+    score_text.append(f"({report.overall_grade})", style=f"bold {grade_color}")
+
+    console.print(Panel(header, title="repo", expand=False))
+    console.print(Panel(score_text, title="overall health score", expand=False))
+
+    table = Table(show_header=True, header_style="bold")
+    table.add_column("Check")
+    table.add_column("Score", justify="right")
+    table.add_column("Grade", justify="center")
+    if verbose:
+        table.add_column("Details")
+
+    for check in report.checks:
+        row = [check.name, str(check.score), _grade_text(check.grade)]
+        if verbose:
+            row.append("\n".join(f"• {d}" for d in check.details))
+        table.add_row(*row)
+
+    console.print(table)
+
+    if not verbose:
+        console.print("[dim]Run with -v for detailed reasoning behind each score.[/dim]")
+
+    if client_rate_hint(report):
+        console.print(
+            "[dim]Tip: set GITHUB_TOKEN to raise your API rate limit from 60/hr to 5000/hr.[/dim]"
+        )
+
+
+def client_rate_hint(report) -> bool:
+    import os
+    return not os.environ.get("GITHUB_TOKEN")
+
+
+if __name__ == "__main__":
+    main()

repocheck_cli-0.1.0/repocheck/github_client.py

@@ -0,0 +1,125 @@
+"""Thin GitHub REST API client used by all checks."""
+from __future__ import annotations
+
+import base64
+import os
+import re
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+import requests
+
+GITHUB_API = "https://api.github.com"
+
+
+class GitHubError(Exception):
+    pass
+
+
+@dataclass
+class RepoRef:
+    owner: str
+    name: str
+
+    @property
+    def full_name(self) -> str:
+        return f"{self.owner}/{self.name}"
+
+
+def parse_repo_arg(arg: str) -> RepoRef:
+    """Accepts 'owner/repo', a full GitHub URL, or a .git URL."""
+    arg = arg.strip()
+
+    # owner/repo shorthand
+    if re.fullmatch(r"[\w.-]+/[\w.-]+", arg):
+        owner, name = arg.split("/", 1)
+        return RepoRef(owner, name.removesuffix(".git"))
+
+    # full URL
+    m = re.search(r"github\.com[:/]+([\w.-]+)/([\w.-]+?)(?:\.git)?/?$", arg)
+    if m:
+        return RepoRef(m.group(1), m.group(2))
+
+    raise ValueError(
+        f"Could not parse repo argument: {arg!r}. "
+        "Use 'owner/repo' or a github.com URL."
+    )
+
+
+class GitHubClient:
+    def __init__(self, token: Optional[str] = None):
+        self.token = token or os.environ.get("GITHUB_TOKEN")
+        self.session = requests.Session()
+        headers = {
+            "Accept": "application/vnd.github+json",
+            "User-Agent": "repocheck-cli",
+            "X-GitHub-Api-Version": "2022-11-28",
+        }
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+        self.session.headers.update(headers)
+        self.rate_remaining: Optional[int] = None
+
+    def _get(self, path: str, **kwargs) -> requests.Response:
+        resp = self.session.get(f"{GITHUB_API}{path}", **kwargs)
+        self.rate_remaining = resp.headers.get("X-RateLimit-Remaining")
+        if resp.status_code == 404:
+            raise GitHubError(f"Not found: {path}")
+        if resp.status_code == 403 and self.rate_remaining == "0":
+            raise GitHubError(
+                "GitHub API rate limit exceeded. Set GITHUB_TOKEN env var "
+                "for a higher limit (60/hr -> 5000/hr)."
+            )
+        resp.raise_for_status()
+        return resp
+
+    def repo(self, ref: RepoRef) -> dict[str, Any]:
+        return self._get(f"/repos/{ref.full_name}").json()
+
+    def contents(self, ref: RepoRef, path: str = "") -> Any:
+        try:
+            return self._get(f"/repos/{ref.full_name}/contents/{path}").json()
+        except GitHubError:
+            return None
+
+    def file_text(self, ref: RepoRef, path: str) -> Optional[str]:
+        data = self.contents(ref, path)
+        if not data or "content" not in data:
+            return None
+        try:
+            return base64.b64decode(data["content"]).decode("utf-8", errors="replace")
+        except Exception:
+            return None
+
+    def workflows(self, ref: RepoRef) -> list[dict[str, Any]]:
+        data = self.contents(ref, ".github/workflows")
+        return data if isinstance(data, list) else []
+
+    def commits(self, ref: RepoRef, per_page: int = 30) -> list[dict[str, Any]]:
+        try:
+            return self._get(
+                f"/repos/{ref.full_name}/commits", params={"per_page": per_page}
+            ).json()
+        except GitHubError:
+            return []
+
+    def issues(self, ref: RepoRef, state: str = "open", per_page: int = 50) -> list[dict[str, Any]]:
+        try:
+            return self._get(
+                f"/repos/{ref.full_name}/issues",
+                params={"state": state, "per_page": per_page},
+            ).json()
+        except GitHubError:
+            return []
+
+    def root_files(self, ref: RepoRef) -> list[str]:
+        data = self.contents(ref, "")
+        if not isinstance(data, list):
+            return []
+        return [item["name"] for item in data if item["type"] == "file"]
+
+    def root_dirs(self, ref: RepoRef) -> list[str]:
+        data = self.contents(ref, "")
+        if not isinstance(data, list):
+            return []
+        return [item["name"] for item in data if item["type"] == "dir"]

repocheck_cli-0.1.0/repocheck/report.py

@@ -0,0 +1,53 @@
+"""Aggregates individual CheckResults into an overall report."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .checks import CHECKS, CheckResult
+from .github_client import GitHubClient, RepoRef
+
+
+@dataclass
+class Report:
+    repo: RepoRef
+    checks: list[CheckResult]
+    overall_score: int
+    overall_grade: str
+    repo_meta: dict
+
+    def to_dict(self) -> dict:
+        return {
+            "repo": self.repo.full_name,
+            "overall_score": self.overall_score,
+            "overall_grade": self.overall_grade,
+            "stars": self.repo_meta.get("stargazers_count"),
+            "forks": self.repo_meta.get("forks_count"),
+            "language": self.repo_meta.get("language"),
+            "checks": [
+                {
+                    "name": c.name,
+                    "score": c.score,
+                    "grade": c.grade,
+                    "details": c.details,
+                }
+                for c in self.checks
+            ],
+        }
+
+
+def run_report(client: GitHubClient, ref: RepoRef) -> Report:
+    repo_meta = client.repo(ref)
+    results = [check_fn(client, ref) for check_fn in CHECKS]
+
+    total_weight = sum(r.weight for r in results)
+    weighted_sum = sum(r.score * r.weight for r in results)
+    overall_score = round(weighted_sum / total_weight) if total_weight else 0
+    overall_grade = CheckResult.grade_for(overall_score)
+
+    return Report(
+        repo=ref,
+        checks=results,
+        overall_score=overall_score,
+        overall_grade=overall_grade,
+        repo_meta=repo_meta,
+    )

repocheck_cli-0.1.0/repocheck_cli.egg-info/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: repocheck-cli
+Version: 0.1.0
+Summary: Scan any GitHub repo and get an instant engineering health report card.
+Author: Syed Ahmed Ali
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Ahmed0754/repocheck
+Project-URL: Repository, https://github.com/Ahmed0754/repocheck
+Project-URL: Issues, https://github.com/Ahmed0754/repocheck/issues
+Keywords: github,cli,code-quality,devtools,ci
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: requests>=2.31
+Requires-Dist: rich>=13.7
+Dynamic: license-file
+
+# repocheck
+
+Scan any public GitHub repo and get an instant engineering health report card — README quality, CI/CD, test presence, dependency hygiene, license, commit activity, and issue hygiene, scored A–F.
+
+```
+$ repocheck pallets/flask
+
+╭─ repo ──────────────────╮
+│ pallets/flask           │
+│ ★ 68234  ⑂ 16200  Python│
+╰──────────────────────────╯
+╭─ overall health score ──╮
+│ 91/100  (A)              │
+╰───────────────────────────╯
+
+Check               Score  Grade
+README Quality        100    A
+CI/CD                  90    A
+Test Presence          85    B
+Dependency Hygiene     80    B
+License               100    A
+Commit Activity        95    A
+Issue Hygiene          85    B
+```
+
+## Install
+
+```bash
+pip install repocheck-cli
+```
+
+## Usage
+
+```bash
+# owner/repo shorthand
+repocheck pallets/flask
+
+# full URL also works
+repocheck https://github.com/psf/requests
+
+# detailed reasoning behind every score
+repocheck torvalds/linux -v
+
+# machine-readable output (for CI pipelines, scripts)
+repocheck your-org/your-repo --json
+```
+
+### Higher rate limits
+
+GitHub's anonymous API limit is 60 requests/hour. `repocheck` makes ~8 requests per scan, so you'll hit that fast without auth. Set a token to bump it to 5,000/hour:
+
+```bash
+export GITHUB_TOKEN=ghp_your_token_here
+repocheck your-org/your-repo
+```
+
+No special scopes needed — a basic personal access token works fine for public repos.
+
+## What it checks
+
+| Check | What it looks at |
+|---|---|
+| **README Quality** | Presence, length, install/usage sections, badges, code blocks |
+| **CI/CD** | GitHub Actions workflows, legacy CI configs |
+| **Test Presence** | Test directories, test config files, declared test scripts |
+| **Dependency Hygiene** | Manifest presence, version pinning, lockfiles |
+| **License** | OSS license presence and type |
+| **Commit Activity** | Recency and message quality of recent commits |
+| **Issue Hygiene** | Open issue count and staleness |
+
+Each check is scored 0–100 and the overall score is an average across all seven.
+
+## Why
+
+Most "is this repo any good" judgments are vibes-based — a glance at stars, maybe the README. `repocheck` turns that into a repeatable, objective-ish checklist you can run on your own repos before sharing them, or use to quickly evaluate a dependency before adopting it.
+
+## Local development
+
+```bash
+git clone https://github.com/Ahmed0754/repocheck
+cd repocheck
+pip install -e ".[dev]"
+repocheck pallets/flask
+```
+
+## License
+
+MIT

repocheck_cli-0.1.0/repocheck_cli.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+repocheck/__init__.py
+repocheck/checks.py
+repocheck/cli.py
+repocheck/github_client.py
+repocheck/report.py
+repocheck_cli.egg-info/PKG-INFO
+repocheck_cli.egg-info/SOURCES.txt
+repocheck_cli.egg-info/dependency_links.txt
+repocheck_cli.egg-info/entry_points.txt
+repocheck_cli.egg-info/requires.txt
+repocheck_cli.egg-info/top_level.txt
+tests/test_checks.py
+tests/test_end_to_end.py
+tests/test_github_client.py

repocheck_cli-0.1.0/repocheck_cli.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

repocheck_cli-0.1.0/repocheck_cli.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+repocheck = repocheck.cli:main

repocheck_cli-0.1.0/repocheck_cli.egg-info/requires.txt

@@ -0,0 +1,3 @@
+click>=8.1
+requests>=2.31
+rich>=13.7

repocheck_cli-0.1.0/repocheck_cli.egg-info/top_level.txt

@@ -0,0 +1 @@
+repocheck

repocheck_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

repocheck_cli-0.1.0/tests/test_checks.py

@@ -0,0 +1,204 @@
+from datetime import datetime, timedelta, timezone
+from unittest.mock import MagicMock
+
+import pytest
+
+from repocheck.checks import (
+    check_activity,
+    check_ci,
+    check_dependencies,
+    check_issue_hygiene,
+    check_license,
+    check_readme,
+    check_tests,
+)
+from repocheck.github_client import RepoRef
+
+REF = RepoRef("acme", "widget")
+
+
+def make_client(**overrides):
+    """Build a MagicMock GitHubClient with sane defaults, override what you need."""
+    client = MagicMock()
+    client.root_files.return_value = overrides.get("root_files", [])
+    client.root_dirs.return_value = overrides.get("root_dirs", [])
+    client.file_text.return_value = overrides.get("file_text", None)
+    client.workflows.return_value = overrides.get("workflows", [])
+    client.commits.return_value = overrides.get("commits", [])
+    client.issues.return_value = overrides.get("issues", [])
+    client.repo.return_value = overrides.get("repo", {})
+    return client
+
+
+# ---------------------------------------------------------------------------
+# README
+# ---------------------------------------------------------------------------
+
+def test_readme_missing():
+    client = make_client(root_files=[])
+    result = check_readme(client, REF)
+    assert result.score == 0
+    assert result.grade == "F"
+
+
+def test_readme_full_quality():
+    text = (
+        "# Widget\n\n" + ("x" * 400) + "\n\n## Installation\npip install widget\n\n"
+        "## Usage\n```python\nimport widget\n```\n\n![CI](https://img.shields.io/badge/ci-passing-green)"
+    )
+    client = make_client(root_files=["README.md"], file_text=text)
+    result = check_readme(client, REF)
+    assert result.score >= 90
+    assert result.grade in ("A", "B")
+
+
+def test_readme_present_but_thin():
+    client = make_client(root_files=["README.md"], file_text="just a title")
+    result = check_readme(client, REF)
+    assert 0 < result.score < 60
+
+
+# ---------------------------------------------------------------------------
+# CI
+# ---------------------------------------------------------------------------
+
+def test_ci_github_actions_present():
+    client = make_client(workflows=[{"name": "ci.yml", "type": "file"}])
+    result = check_ci(client, REF)
+    assert result.score >= 70
+
+
+def test_ci_none():
+    client = make_client(workflows=[], root_files=["README.md"])
+    result = check_ci(client, REF)
+    assert result.score == 0
+    assert result.grade == "F"
+
+
+def test_ci_legacy_travis():
+    client = make_client(workflows=[], root_files=[".travis.yml"])
+    result = check_ci(client, REF)
+    assert 0 < result.score < 90
+
+
+# ---------------------------------------------------------------------------
+# Tests presence
+# ---------------------------------------------------------------------------
+
+def test_tests_dir_present():
+    client = make_client(root_dirs=["tests"], root_files=[])
+    result = check_tests(client, REF)
+    assert result.score >= 60
+
+
+def test_tests_absent():
+    client = make_client(root_dirs=["src"], root_files=["main.py"])
+    result = check_tests(client, REF)
+    assert result.score == 0
+
+
+def test_tests_config_only():
+    client = make_client(root_dirs=[], root_files=["pytest.ini"])
+    result = check_tests(client, REF)
+    assert result.score == 25
+
+
+# ---------------------------------------------------------------------------
+# Dependencies
+# ---------------------------------------------------------------------------
+
+def test_dependencies_pinned_requirements():
+    text = "flask==2.3.0\nrequests==2.31.0\nclick==8.1.7\n"
+    client = make_client(root_files=["requirements.txt"], file_text=text)
+    result = check_dependencies(client, REF)
+    assert result.score >= 80
+
+
+def test_dependencies_unpinned_requirements():
+    text = "flask\nrequests\nclick\n"
+    client = make_client(root_files=["requirements.txt"], file_text=text)
+    result = check_dependencies(client, REF)
+    assert result.score == 70  # baseline only, no pin bonus
+
+
+def test_dependencies_none_found():
+    client = make_client(root_files=["README.md"])
+    result = check_dependencies(client, REF)
+    assert result.score == 50  # neutral, not penalized
+
+
+# ---------------------------------------------------------------------------
+# License
+# ---------------------------------------------------------------------------
+
+def test_license_detected_by_api():
+    client = make_client(repo={"license": {"name": "MIT License", "spdx_id": "MIT"}})
+    result = check_license(client, REF)
+    assert result.score == 100
+
+
+def test_license_file_only():
+    client = make_client(repo={"license": None}, root_files=["LICENSE"])
+    result = check_license(client, REF)
+    assert result.score == 80
+
+
+def test_license_missing():
+    client = make_client(repo={"license": None}, root_files=["README.md"])
+    result = check_license(client, REF)
+    assert result.score == 0
+
+
+# ---------------------------------------------------------------------------
+# Activity
+# ---------------------------------------------------------------------------
+
+def _commit(days_ago: int, message: str):
+    date = (datetime.now(timezone.utc) - timedelta(days=days_ago)).isoformat().replace("+00:00", "Z")
+    return {"commit": {"committer": {"date": date}, "message": message}}
+
+
+def test_activity_recent_and_descriptive():
+    commits = [_commit(1, "Add retry logic to API client for transient failures")]
+    client = make_client(commits=commits)
+    result = check_activity(client, REF)
+    assert result.score >= 80
+
+
+def test_activity_stale_repo():
+    commits = [_commit(500, "fix")]
+    client = make_client(commits=commits)
+    result = check_activity(client, REF)
+    assert result.score < 50
+
+
+def test_activity_no_commits():
+    client = make_client(commits=[])
+    result = check_activity(client, REF)
+    assert result.score == 0
+
+
+# ---------------------------------------------------------------------------
+# Issue hygiene
+# ---------------------------------------------------------------------------
+
+def test_issue_hygiene_zero_open():
+    client = make_client(repo={"open_issues_count": 0})
+    result = check_issue_hygiene(client, REF)
+    assert result.score == 100
+
+
+def test_issue_hygiene_all_fresh():
+    fresh = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+    issues = [{"created_at": fresh} for _ in range(5)]
+    client = make_client(repo={"open_issues_count": 5}, issues=issues)
+    result = check_issue_hygiene(client, REF)
+    assert result.score == 100
+
+
+def test_issue_hygiene_all_stale():
+    old = (datetime.now(timezone.utc) - timedelta(days=400)).isoformat().replace("+00:00", "Z")
+    issues = [{"created_at": old} for _ in range(5)]
+    client = make_client(repo={"open_issues_count": 5}, issues=issues)
+    result = check_issue_hygiene(client, REF)
+    assert result.score == 20

repocheck_cli-0.1.0/tests/test_end_to_end.py

@@ -0,0 +1,88 @@
+"""End-to-end test: mocks GitHub's HTTP responses and runs a full report."""
+import json
+from unittest.mock import MagicMock, patch
+
+from repocheck.github_client import GitHubClient, parse_repo_arg
+from repocheck.report import run_report
+
+FAKE_REPO_META = {
+    "full_name": "acme/widget",
+    "stargazers_count": 1234,
+    "forks_count": 56,
+    "language": "Python",
+    "license": {"name": "MIT License", "spdx_id": "MIT"},
+    "open_issues_count": 2,
+}
+
+FAKE_README = (
+    "# Widget\n\nA delightful widget library.\n\n"
+    "## Installation\n```\npip install widget\n```\n\n"
+    "## Usage\n```python\nimport widget\nwidget.run()\n```\n\n"
+    "![build](https://img.shields.io/badge/build-passing-green)\n"
+) * 3  # pad past the 300-char threshold
+
+
+def _fake_response(json_data, status=200, headers=None):
+    resp = MagicMock()
+    resp.status_code = status
+    resp.json.return_value = json_data
+    resp.headers = headers or {"X-RateLimit-Remaining": "59"}
+    resp.raise_for_status = MagicMock()
+    return resp
+
+
+def fake_get(url, params=None, **kwargs):
+    if url.endswith("/repos/acme/widget"):
+        return _fake_response(FAKE_REPO_META)
+    if "/contents/" in url and url.endswith("/contents/"):
+        return _fake_response([
+            {"name": "README.md", "type": "file"},
+            {"name": "requirements.txt", "type": "file"},
+            {"name": "tests", "type": "dir"},
+            {"name": "src", "type": "dir"},
+        ])
+    if url.endswith("/contents/README.md"):
+        import base64
+        return _fake_response({"content": base64.b64encode(FAKE_README.encode()).decode()})
+    if url.endswith("/contents/requirements.txt"):
+        import base64
+        return _fake_response({"content": base64.b64encode(b"flask==2.3.0\nrequests==2.31.0\n").decode()})
+    if url.endswith("/contents/.github/workflows"):
+        return _fake_response([{"name": "ci.yml", "type": "file"}])
+    if url.endswith("/commits"):
+        return _fake_response([
+            {
+                "commit": {
+                    "committer": {"date": "2026-06-15T12:00:00Z"},
+                    "message": "Add retry logic for transient network failures",
+                }
+            }
+        ])
+    if url.endswith("/issues"):
+        return _fake_response([])
+    # default: not found
+    return _fake_response({"message": "Not Found"}, status=404)
+
+
+def test_end_to_end_report_with_mocked_api():
+    ref = parse_repo_arg("acme/widget")
+    client = GitHubClient(token="fake-token")
+
+    with patch.object(client.session, "get", side_effect=fake_get):
+        report = run_report(client, ref)
+
+    assert report.repo.full_name == "acme/widget"
+    assert 0 <= report.overall_score <= 100
+    assert report.overall_grade in ("A", "B", "C", "D", "F")
+    assert len(report.checks) == 7
+
+    as_dict = report.to_dict()
+    # Confirm it's JSON-serializable end to end, like --json mode produces
+    serialized = json.dumps(as_dict)
+    assert "acme/widget" in serialized
+
+    # Sanity check a couple of specific checks given our fake data
+    names = {c.name: c for c in report.checks}
+    assert names["License"].score == 100
+    assert names["CI/CD"].score >= 70
+    assert names["Issue Hygiene"].score == 90  # count=2 but issues list empty -> "possibly all PRs" branch

repocheck_cli-0.1.0/tests/test_github_client.py

@@ -0,0 +1,31 @@
+import pytest
+
+from repocheck.github_client import parse_repo_arg, RepoRef
+
+
+@pytest.mark.parametrize(
+    "arg,expected_owner,expected_name",
+    [
+        ("pallets/flask", "pallets", "flask"),
+        ("https://github.com/psf/requests", "psf", "requests"),
+        ("https://github.com/psf/requests.git", "psf", "requests"),
+        ("git@github.com:torvalds/linux.git", "torvalds", "linux"),
+        ("github.com/Ahmed0754/repocheck", "Ahmed0754", "repocheck"),
+        ("github.com/Ahmed0754/repocheck/", "Ahmed0754", "repocheck"),
+    ],
+)
+def test_parse_repo_arg_valid(arg, expected_owner, expected_name):
+    ref = parse_repo_arg(arg)
+    assert ref.owner == expected_owner
+    assert ref.name == expected_name
+
+
+def test_parse_repo_arg_full_name():
+    ref = parse_repo_arg("octocat/Hello-World")
+    assert ref.full_name == "octocat/Hello-World"
+
+
+@pytest.mark.parametrize("bad_arg", ["", "not a repo", "just-a-word", "http://example.com/foo/bar"])
+def test_parse_repo_arg_invalid(bad_arg):
+    with pytest.raises(ValueError):
+        parse_repo_arg(bad_arg)