Metadata-Version: 2.5
Name: repo-health-scanner
Version: 0.1.0
Summary: Check Python repo health and open safe draft PRs for docstrings and patch deps
Project-URL: Homepage, https://github.com/pranavraj101/repo-health-scanner
Project-URL: Repository, https://github.com/pranavraj101/repo-health-scanner
Author: Pranav Raj
License-Expression: MIT
License-File: LICENSE
Keywords: dependencies,docstring,health,lint,python,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: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Requires-Dist: packaging>=23.0
Requires-Dist: pygithub>=2.1.0
Requires-Dist: rich>=13.0.0
Requires-Dist: tomli>=2.0.0; python_version < '3.11'
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Provides-Extra: llm-anthropic
Requires-Dist: anthropic>=0.25.0; extra == 'llm-anthropic'
Provides-Extra: llm-openai
Requires-Dist: openai>=1.0.0; extra == 'llm-openai'
Description-Content-Type: text/markdown

# 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`](docs/PUBLISHING.md)):

```bash
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:

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

**Before PyPI:** install from GitHub:

```bash
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)

```bash
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”:

```bash
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)

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

### C. `.env` inside the project being scanned

```bash
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`](examples/github-workflow-consumer.yml).

### OpenAI instead of Anthropic

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

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

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

## License

MIT
