codebase-health-score

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:

pip install codebase-health-score

Quick Start

Analyze a repository:

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:

# 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

# 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 - Python Git bindings
• Click - CLI framework
• Rich - 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 file for details.

---

Built by Glue — AI codebase intelligence for product teams. If you want deeper analysis including feature discovery, tribal knowledge extraction, and natural language querying, check out Glue.