repo-health 1.0.0

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

pip install repo-health

Usage

# 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+)

Configuration

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

[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:

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

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

GitHub Action

- 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