Metadata-Version: 2.4
Name: repo-health
Version: 1.0.0
Summary: CLI tool that scans a Git repository and produces a health score (0-100) based on 20+ signals
Project-URL: Homepage, https://github.com/repo-health/repo-health
Project-URL: Issues, https://github.com/repo-health/repo-health/issues
Author: Repo Health Contributors
License-Expression: MIT
License-File: LICENSE
Keywords: audit,cli,git,health,quality,repository
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Requires-Dist: gitpython>=3.1.0
Requires-Dist: rich>=13.0.0
Requires-Dist: tomli>=2.0.0; python_version < '3.11'
Requires-Dist: typer>=0.9.0
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <img src="assets/repo-health.png" alt="Repo Health CLI logo" width="180" height="180">
</p>
# repo-health

[![CI](https://github.com/bhayanak/repo-health/actions/workflows/ci.yml/badge.svg)](https://github.com/bhayanak/repo-health/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/repo-health)](https://pypi.org/project/repo-health/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

**CLI tool that scans a Git repository and produces a health score (0-100) based on 20+ signals.**

No single CLI tool gives a holistic repo health score with actionable recommendations. `repo-health` fills that gap — run it locally, in CI, or as a GitHub Action.

## Install

```bash
pip install repo-health
```

## Usage

```bash
# Scan current directory
repo-health

# Scan specific path
repo-health scan /path/to/repo

# JSON output for CI
repo-health scan --format json --output report.json

# Markdown report
repo-health scan --format markdown --output HEALTH.md

# Generate badge SVG
repo-health badge --output health-badge.svg

# Fail CI if below threshold
repo-health scan --min-score 70

# CI mode (JSON output, non-zero exit on failure)
repo-health scan --ci --min-score 60
```

## Output Example

```
╭─────────────────────────────────────────────╮
│           🏥 Repository Health Report        │
│           my-project  ·  Score: 78/100  B+   │
╰─────────────────────────────────────────────╯

┌────────────┬───────┬────────────────────────────────┐
│ Category   │ Score │ Details                         │
├────────────┼───────┼────────────────────────────────┤
│ CI/CD      │ 90    │ ✅ CI config, ✅ tests in CI     │
│ Testing    │ 70    │ ✅ Tests exist, ⚠️ No coverage   │
│ Docs       │ 85    │ ✅ README, ✅ LICENSE, ❌ CHANGELOG│
│ Security   │ 60    │ ✅ .gitignore, ❌ SECURITY.md    │
│ Deps       │ 75    │ ✅ Lock file, ⚠️ 3 outdated      │
│ Community  │ 80    │ ✅ Issue template, ❌ COC         │
│ Release    │ 70    │ ✅ Tags, ❌ No release notes      │
│ Git        │ 90    │ ✅ Clean history                  │
└────────────┴───────┴────────────────────────────────┘

💡 Top Recommendations:
  1. Add CHANGELOG.md to track version history
  2. Create SECURITY.md with vulnerability reporting process
  3. Add coverage reporting to CI pipeline
```

## Health Signals (20+)

| Category | Signals |
|----------|---------|
| **CI/CD** | CI config exists, tests run in CI, build step, deploy step |
| **Testing** | Test files exist, coverage config, coverage threshold |
| **Documentation** | README quality (sections, badges), CONTRIBUTING, CHANGELOG, LICENSE |
| **Security** | .gitignore completeness, no secrets in repo, SECURITY.md, dependency audit |
| **Dependencies** | Manifest exists, lock file, version pinning, audit tool |
| **Community** | Issue templates, PR templates, CODE_OF_CONDUCT, CONTRIBUTING |
| **Release** | Tagged releases, semantic versioning, release notes |
| **Git Hygiene** | Git repo, commit message quality, default branch |

## Configuration

Create `.repo-health.toml` in your repo root:

```toml
[weights]
ci = 15
testing = 20
documentation = 10
security = 15
dependencies = 10
community = 10
release = 10
git_hygiene = 10

[thresholds]
min_score = 70

[ignore]
scanners = []
files = ["vendor/"]
```

Or add to `pyproject.toml`:

```toml
[tool.repo-health.weights]
testing = 20

[tool.repo-health.thresholds]
min_score = 70
```

## GitHub Action

```yaml
- uses: repo-health/repo-health@v1
  with:
    min-score: 60
    format: json
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Run tests: `pytest --cov`
4. Submit a pull request

## License

[MIT](LICENSE)
