Metadata-Version: 2.4
Name: gh-score
Version: 0.10.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).

## 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
```

### 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
```

### Configuration

Set a `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.

## 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
```

## License

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