142 lines
3.3 KiB
Markdown
142 lines
3.3 KiB
Markdown
# 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.
|