# RepoHealth CLI

A CLI tool that analyzes Git repositories to calculate bus factor scores, identify knowledge concentration hotspots, and generate actionable risk reports. It helps team leads and maintainers understand single-points-of-failure risks in their codebase.

## Features

- **Bus Factor Calculation**: Calculate bus factor scores per file/module based on commit authorship distribution
- **Hotspot Identification**: Identify knowledge concentration hotspots where code ownership is concentrated
- **Risk Heatmaps**: Generate visual risk heatmaps showing file/module risk levels
- **Diversification Suggestions**: Suggest strategies to diversify code ownership
- **Multiple Output Formats**: Export analysis results in JSON, HTML, or terminal display

## Installation

```bash
pip install repohealth-cli
```

Or from source:

```bash
pip install -e .
```

## Quick Start

Analyze the current repository:

```bash
repohealth analyze
```

Analyze a specific repository:

```bash
repohealth analyze /path/to/repository
```

Generate an HTML report:

```bash
repohealth report /path/to/repository --format html --output report.html
```

## Commands

### analyze

Perform a full repository analysis:

```bash
repohealth analyze [REPO_PATH] [OPTIONS]
```

Options:
- `--depth`: Limit commit history depth (default: unlimited)
- `--path`: Analyze specific paths within the repository
- `--extensions`: Filter by file extensions (e.g., "py,js,ts")
- `--min-commits`: Minimum commits to consider a file (default: 1)

### report

Generate a detailed report:

```bash
repohealth report [REPO_PATH] [OPTIONS]
```

Options:
- `--format`: Output format (json, html, terminal)
- `--output`: Output file path (for json/html formats)
- `--depth`: Limit commit history depth
- `--path`: Analyze specific paths

## Output Formats

### Terminal

Rich terminal output with colored tables and progress bars.

### JSON

Machine-readable output for integration with other tools:

```json
{
  "repository": "/path/to/repo",
  "analyzed_at": "2024-01-15T10:30:00Z",
  "bus_factor_overall": 2.3,
  "files_analyzed": 150,
  "high_risk_files": 12,
  "files": [...],
  "hotspots": [...],
  "suggestions": [...]
}
```

### HTML

Interactive HTML report with visualizations and charts.

## Configuration

Create a `repohealth.config.json` in your repository root:

```json
{
  "depth": 365,
  "extensions": ["py", "js", "ts", "go"],
  "path": "src",
  "min_commits": 5,
  "risk_threshold": 0.7
}
```

## Understanding Bus Factor

The **Bus Factor** measures how many developers would need to be hit by a bus before the project is in serious trouble. A higher bus factor indicates better knowledge distribution.

- **Bus Factor 1**: Single point of failure - one person knows everything about this code
- **Bus Factor 2+**: Multiple people understand the code
- **Bus Factor > 3**: Healthy knowledge distribution

## Risk Levels

- **Critical** (< 1.5): Immediate attention needed - single author majority
- **High** (1.5 - 2.0): Multiple authors but concentration exists
- **Medium** (2.0 - 3.0): Moderate distribution
- **Low** (> 3.0): Good knowledge distribution

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: `pytest tests/ -v`
5. Submit a pull request

## License

MIT License - see LICENSE file for details.