repohealth-cli/README.md

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

pip install repohealth-cli

Or from source:

pip install -e .

Quick Start

Analyze the current repository:

repohealth analyze

Analyze a specific repository:

repohealth analyze /path/to/repository

Generate an HTML report:

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

Commands

analyze

Perform a full repository analysis:

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:

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:

{
  "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:

{
  "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.