Repo Health Scanner

Check repo health for Python projects: documentation, dependency freshness, and bare except: hygiene. Prints a transparent 0–100 score and can open draft PRs for safe fixes (docstrings, patch-level dependency bumps).

Install once, run anywhere: check-repo-health scan /path/to/any/repo.

Install

From PyPI (after you publish — see docs/PUBLISHING.md):

pip install repo-health-scanner
# or isolated CLI tool:
pipx install repo-health-scanner
pipx inject repo-health-scanner anthropic   # only for auto-fix / draft PRs

With LLM extras in one step:

pip install "repo-health-scanner[llm-anthropic]"

Before PyPI: install from GitHub:

pip install "git+https://github.com/pranavraj101/repo-health-scanner.git@main[llm-anthropic]"

Package name is repo-health-scanner (hyphens). The shell command is check-repo-health, not repo health scanner.

Scan (no API keys)

check-repo-health scan /path/to/python/repo
check-repo-health scan /path/to/python/repo --json

Setting your Anthropic key (BYOK)

Scanning never calls an LLM. You only need a key for --open-prs / run (docstring text).

Pick one approach:

A. Recommended with pipx — user config file

Works from any directory; best for “installed once, use on many repos”:

check-repo-health config init
# opens ~/.config/repo-health-scanner/env — add:
#   ANTHROPIC_API_KEY=sk-ant-...
#   REPO_HEALTH_LLM_PROVIDER=anthropic

check-repo-health config path    # show path anytime

The CLI loads, in order: shell env → ~/.config/repo-health-scanner/env → .env in the repo you are scanning.

B. Shell export (session or ~/.zshrc)

export ANTHROPIC_API_KEY=sk-ant-...
export REPO_HEALTH_LLM_PROVIDER=anthropic

C. .env inside the project being scanned

cd /path/to/their/repo
echo 'ANTHROPIC_API_KEY=sk-ant-...' >> .env   # do not commit this file
check-repo-health scan . --open-prs

D. GitHub Actions (their repo)

Repository Settings → Secrets → Actions:

• ANTHROPIC_API_KEY (required for auto-fix in CI)
• GITHUB_TOKEN is provided automatically

Use examples/github-workflow-consumer.yml.

OpenAI instead of Anthropic

export OPENAI_API_KEY=sk-...
export REPO_HEALTH_LLM_PROVIDER=openai
pipx inject repo-health-scanner openai

Variable	When
ANTHROPIC_API_KEY	Auto-fix with Anthropic
OPENAI_API_KEY	Auto-fix with OpenAI
REPO_HEALTH_LLM_PROVIDER	anthropic or openai if both keys exist
REPO_HEALTH_ANTHROPIC_MODEL	Default claude-3-5-haiku-20241022
REPO_HEALTH_OPENAI_MODEL	Default gpt-4o-mini
GITHUB_TOKEN	Local draft PRs (gh auth token or PAT)

Auto-fix + draft PR

export GITHUB_TOKEN=$(gh auth token)
cd /path/to/their/repo
check-repo-health scan . --open-prs --base-branch main

CI entrypoint: check-repo-health run . --issue 42

Scoring

score = 100
      - (undocumented_public / total_public) * 40
      - (outdated_packages / total_packages) * 30
      - min(bare_except_blocks * 2, 30)

History: .repo-health/history.json in the scanned repo.

Safety rules

1. Hardcoded fix types only (docstrings + patch deps).
2. Fixes must pass tests (+ Ruff when available).
3. No tests → no dependency PRs.
4. Draft PRs only; one category per PR.
5. Scanning is static; LLM only for docstring wording.

Development

git clone https://github.com/pranavraj101/repo-health-scanner.git
cd repo-health-scanner
pip install -e ".[dev]"
pytest

License

MIT