repo-health 1.0.0

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

# repo-health

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

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:

[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