Metadata-Version: 2.4
Name: gh-score
Version: 0.15.0
Summary: GitHub Project Health Scorer - evaluate maturity, maintenance, community health and sustainability
Keywords: github,health,maintenance,scoring,audit,sustainability
Author: Mathieu Lecarme
Author-email: Mathieu Lecarme <mathieu@garambrogne.net>
License-Expression: GPL-3.0-only
License-File: LICENSE
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Dist: httpx>=0.27
Requires-Dist: rich>=13.0
Requires-Dist: click>=8.1
Requires-Dist: platformdirs>=4.0
Requires-Dist: gitpython>=3.1.57
Requires-Python: >=3.12
Project-URL: Homepage, https://github.com/athoune/github-score
Project-URL: Repository, https://github.com/athoune/github-score
Project-URL: Issues, https://github.com/athoune/github-score/issues
Description-Content-Type: text/markdown

# gh-score

GitHub Project Health Scorer — evaluate maturity, maintenance, community health and sustainability of any GitHub project, in your terminal.

`gh-score` turns raw GitHub signals (commit activity, contributors, releases, license, registries, sustainability) into a single **traffic-light verdict**: 🟢 green (safe to bet on), 🟠 orange (proceed with caution), 🔴 red (risky).

When a repository declares a homepage, `gh-score` also checks that the
application's web page is actually reachable — DNS resolution, timeouts,
HTTP status (redirects followed) — and flags pages hidden behind a
bot-protection check ("I'm not a robot"). A dead homepage is a red flag
for the verdict.

## Usage

```bash
# Analyze a remote repository (no install needed)
uvx gh-score https://github.com/owner/repo

# Analyze the current directory (if it's a git clone)
uvx gh-score

# Or install it
pip install gh-score
gh-score https://github.com/owner/repo
```

### Output formats

```bash
gh-score --format tui       https://github.com/owner/repo   # terminal dashboard (default)
gh-score --format markdown  https://github.com/owner/repo   # Markdown report
gh-score --format json      https://github.com/owner/repo   # structured JSON
```

### Compare projects

Pass two or more URLs to compare them side by side — e.g. to pick
between similar libraries:

```bash
gh-score https://github.com/fastapi/fastapi https://github.com/pallets/flask https://github.com/django/django
gh-score --format markdown https://github.com/BurntSushi/ripgrep https://github.com/sharkdp/fd
```

The comparison checks that it is **credible**: each pair is assessed for
subject comparability (shared topics / description keywords), language
compatibility for libraries, and library-vs-application mismatches.
Non-credible pairs are flagged with the reason — warnings never block
the comparison.

The output is a **decision table**: one line per project (stars,
license, language, maintenance state, last commit, bus factor,
downloads, latest release, traffic-light verdict), ranked by verdict,
then downloads, then bus factor. Each pair also shows an informational
similarity score (0.0–1.0) saying how close the expressed subjects are.

### Optional LLM analysis

The LLM is opt-in and never required. It extracts qualitative facts that
cannot be derived from APIs or files (roadmap, commercial support,
security policy, self-declared maintenance state) and produces a refined,
complementary recommendation that weighs all indicators together.

```bash
export GH_SCORE_LLM_ENABLED=true
export GH_SCORE_LLM_BASE_URL="https://api.openai.com/v1"   # any OpenAI-compatible API
export GH_SCORE_LLM_MODEL="gpt-4o-mini"
export GH_SCORE_LLM_API_KEY="sk-..."
gh-score https://github.com/owner/repo
```

**Reasoning models** (Qwen-style "thinking", DeepSeek R1, …) spend the
whole token budget on chain-of-thought and get cut off before emitting
the JSON. If your model produces "empty or unparseable JSON response"
warnings, disable the reasoning pass:

```bash
export GH_SCORE_LLM_DISABLE_REASONING=true
```

The provider then asks the server to skip reasoning
(`chat_template_kwargs.enable_thinking: false`, honored by oMLX / vLLM /
llama.cpp-style servers, plus the OpenAI-compatible
`reasoning_effort: "none"`). Opt-in: only set it for reasoning models.

### Configuration

Set a `GH_SCORE_GITHUB_TOKEN` to raise API rate limits. LLM settings can also live
in a `config.toml` (see `gh-score config`). Everything stays optional:
the tool works fully offline with local clones and no token.

`gh-score` reads settings from the environment and from `config.toml`
only: it never loads a `.env` file. Export the variables yourself.

To enrich the report with **dependents counts** (how many packages depend
on this library) for PyPI, npm and Maven — the only ecosystems whose
official registries expose no reverse-dependency count — set a free
[libraries.io](https://libraries.io/api) API key (60 requests/minute):

```bash
export LIBRARIES_IO_API_KEY="..."
# or in config.toml:
# [registries]
# libraries_io_api_key = "..."
```

crates.io, RubyGems and Go (pkg.go.dev) always provide their own dependents
count; downloads are always fetched where the registry exposes them.

## Library

```python
from gh_score import analyze_repo

result = analyze_repo("https://github.com/owner/repo")
print(result.recommendation.level)  # RecommendationLevel.GREEN
print(result.release_health.latest_version)  # "v1.0.0"
print(result.contributors.bus_factor)  # 3
```

## Screenshot

![gh-score in a terminal](./screenshots/gh-score-0-10.png)

## License

GPL-3.0 — see [LICENSE](LICENSE).
