codebase-health-score 1.0.0
Calculate a health score for any Git repository
License: MIT
Requires Python: >=3.8
Keywords: git, repository, analysis, health, metrics, code-quality

# codebase-health-score

[![PyPI version](https://badge.fury.io/py/codebase-health-score.svg)](https://badge.fury.io/py/codebase-health-score)
[![Python Versions](https://img.shields.io/pypi/pyversions/codebase-health-score.svg)](https://pypi.org/project/codebase-health-score/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Calculate a health score for any Git repository. Analyzes code complexity, documentation coverage, dependency freshness, test presence, and contributor bus factor.

## Installation

Install via pip:

```bash
pip install codebase-health-score
```

## Quick Start

Analyze a repository:

```bash
codebase-health analyze /path/to/repo
```

Sample output:

```
Repository Health Analysis: /path/to/repo

Overall Score: 73/100 (Good)

┏━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━┓
┃ Dimension            ┃ Score  ┃ Status    ┃
┡━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━┩
│ Code Complexity      │ 18/25  │ Good      │
│ Documentation        │ 16/20  │ Good      │
│ Test Coverage        │ 15/20  │ Fair      │
│ Dependency Health    │ 12/15  │ Fair      │
│ Git & Collaboration  │ 12/20  │ Fair      │
└──────────────────────┴────────┴───────────┘

Key Findings:
• Repository has 42 Python files with average size of 124 lines
• README.md exists, but CONTRIBUTING.md is missing
• Test directory present: 18 test files found
• 6 active contributors, bus factor at 34% (top contributor)
• Last commit 2 days ago
```

Generate detailed reports:

```bash
# Table format (default)
codebase-health report /path/to/repo --format table

# JSON format for integration
codebase-health report /path/to/repo --format json

# Markdown format
codebase-health report /path/to/repo --format markdown

# Save to file
codebase-health report /path/to/repo --output-file health_report.json
```

## How Scoring Works

### Code Complexity (25 points)

Evaluates the structural complexity of your codebase:

- **File Size**: Measures average and maximum file sizes. Large files indicate potential complexity.
- **Directory Depth**: Checks nesting levels. Excessive nesting suggests organizational issues.
- **File Count**: Considers total files. Very small or very large codebases may have organization concerns.

**Good**: Average file size 100-200 lines, max file under 500 lines, directory depth under 5 levels

### Documentation (20 points)

Assesses how well your project is documented:

- **README**: Presence of README.md is essential
- **Contributing Guide**: CONTRIBUTING.md indicates mature projects
- **Docstrings**: Ratio of documented functions/classes
- **Code Comments**: Inline comment density in source files

**Good**: README present, some docstrings, reasonable comment coverage

### Test Coverage Indicators (20 points)

Evaluates testing infrastructure:

- **Test Directory**: Presence of tests/ or test directory
- **Test File Ratio**: Proportion of test files to source files
- **CI Configuration**: Presence of .github/workflows, .gitlab-ci.yml, etc.

**Good**: 1 test file per 3-4 source files, CI pipeline configured

### Dependency Health (15 points)

Checks dependency management practices:

- **Lock File**: Presence of requirements.txt, poetry.lock, package-lock.json, etc.
- **Dependency Count**: Reasonable number of direct dependencies
- **Freshness**: Heuristic based on repository age and activity

**Good**: Lock file present, under 50 direct dependencies, recent updates

### Git & Collaboration (20 points)

Analyzes repository health and team dynamics:

- **Commit Frequency**: Regular commits indicate active maintenance
- **Contributor Count**: Diversity of contributors
- **Bus Factor**: Risk mitigation - not overly dependent on single contributor
- **Recent Activity**: Last commit within reasonable timeframe

**Good**: Multiple commits per month, 5+ contributors, bus factor below 40%, active within 30 days

## Available Commands

```bash
# Analyze a repository with default settings
codebase-health analyze .

# Analyze with verbose output
codebase-health analyze /path/to/repo --verbose

# Generate detailed report in JSON format
codebase-health report . --format json

# Save markdown report
codebase-health report . --format markdown --output-file report.md

# See help
codebase-health --help
codebase-health analyze --help
```

## Requirements

- Python 3.8+
- Git (for repository analysis)

## Built With

- [GitPython](https://github.com/gitpython-developers/GitPython) - Python Git bindings
- [Click](https://click.palletsprojects.com/) - CLI framework
- [Rich](https://rich.readthedocs.io/) - Beautiful terminal rendering

## Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit changes (`git commit -m 'Add amazing feature'`)
4. Push to branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see [LICENSE](LICENSE) file for details.

---

**Built by [Glue](https://glue.tools)** — AI codebase intelligence for product teams. If you want deeper analysis including feature discovery, tribal knowledge extraction, and natural language querying, check out Glue.