@glue-tools-ai/codebase-health-score

Calculate a comprehensive health score for any Git repository. Analyzes code complexity, documentation coverage, test presence, dependency health, and contributor patterns to give you actionable insights into your codebase quality.

Features

• 5 Scoring Dimensions - Comprehensive analysis across multiple aspects of code health
• 0-100 Health Score - Easy to understand overall health metric
• Multiple Output Formats - Table, JSON, and Markdown output options
• Git Integration - Analyzes commit history and contributor patterns
• Fast & Lightweight - Analyzes repositories in seconds
• No Installation Required - Run with npx for instant analysis

Installation

Using npx (Recommended)

Run instantly without installation:

npx @glue-tools-ai/codebase-health-score analyze .

Global Installation

Install globally for repeated use:

npm install -g @glue-tools-ai/codebase-health-score

Local Installation

Install in a project:

npm install --save-dev @glue-tools-ai/codebase-health-score

Quick Start

Basic Analysis

Analyze the current repository:

npx @glue-tools-ai/codebase-health-score analyze .

Analyze Another Repository

npx @glue-tools-ai/codebase-health-score analyze /path/to/repo

Generate Detailed Report

npx @glue-tools-ai/codebase-health-score report . --format markdown

Sample Output

╔════════════════════════════════════════╗
║   CODEBASE HEALTH ANALYSIS REPORT     ║
╚════════════════════════════════════════╝

Overall Health Score
████████████████████████████░░          75/100 (Good)

╔ Scoring Breakdown ════════════════════╗
║ Code Complexity                    22/25
║  Avg File Size: 2048 bytes | Large Files: 0 | Max Depth: 4
║ Documentation                     18/20
║  README • LICENSE • CONTRIBUTING | Comments: 12%
║ Test Coverage                     15/20
║  Test Files: 8 | Ratio: 25.5% | CI/CD: Yes
║ Dependency Health                 12/15
║  Dependencies: 8 | Dev: 12 | Lock File: npm
║ Git Health                        16/20
║  Commits: 156 | Contributors: 3 | Bus Factor: 2
╚═══════════════════════════════════════╝

Repository: /path/to/repo
Analyzed: 2/16/2026, 10:30:45 AM

Scoring Dimensions

Code Complexity (25 points)

Evaluates the structural complexity of your codebase:

• Average File Size - Measures file manageability (smaller is better)
• Large Files - Flags files over 500KB that may need refactoring
• Directory Depth - Checks for overly nested folder structures
• Total File Count - Provides context on project scale

Scoring:

• Penalized for files over 500KB
• Penalized for directory depth exceeding 8 levels
• Penalized for average file size over 5KB

Documentation (20 points)

Assesses documentation quality and code comments:

• README - 6 points (most critical)
• LICENSE - 3 points
• CONTRIBUTING Guide - 3 points
• CHANGELOG - 2 points
• Code of Conduct - 2 points
• Code Comments - Up to 4 points based on comment ratio

Scoring:

• README present = 6 points
• Each supporting document = 2-3 points
• Higher comment ratio = more points (10% = 2pts, 20% = 4pts)

Test Coverage (20 points)

Evaluates testing infrastructure:

• Test Files - Presence of .test.js or .spec.js files (10 points)
• Test Ratio - Proportion of test files to source files (up to 5 points)
• CI/CD Configuration - GitHub Actions, CircleCI, Travis, etc. (5 points)

Scoring:

• Test files present = 10 points
• 50%+ test ratio = 5 bonus points
• 25%+ test ratio = 3 bonus points
• 10%+ test ratio = 1 bonus point
• CI/CD configured = 5 points

Dependency Health (15 points)

Assesses dependency management practices:

• package.json - Presence of dependency manifest (3 points)
• Lock File - npm, yarn, or pnpm lock file (4 points)
• Dependency Count - Reasonable number of dependencies (8 points)

Scoring:

• Has package.json = 3 points
• Has lock file = 4 points
• 1-100 dependencies = 8 points
• 100-200 dependencies = 4 points
• 200+ dependencies = 0 points

Git Health (20 points)

Analyzes repository history and collaboration:

• Commit Frequency - Total commits and activity level (8 points)
• Contributors - Number of people contributing (6 points)
• Bus Factor - Knowledge distribution among contributors (4 points)
• Recent Activity - Days since last commit (2 points)

Scoring:

• 50+ commits = 8 points, 20+ commits = 5 points, 5+ commits = 2 points
• 5+ contributors = 6 points, 2+ contributors = 4 points, 1 contributor = 1 point
• 3+ key contributors = 4 points, 2+ contributors = 2 points
• Last commit within 90 days = 2 points

Usage

Command: analyze

Run full analysis on a repository:

codebase-health analyze [path] [options]

Options:

• --format <format> - Output format: table (default), json, or markdown
• -v, --verbose - Show detailed analysis output
• -o, --output <file> - Write report to a file

Examples:

# Analyze current directory with table format
codebase-health analyze .

# Analyze with verbose output
codebase-health analyze . --verbose

# Generate JSON report
codebase-health analyze /path/to/repo --format json

# Save report to file
codebase-health analyze . --format markdown -o report.md

Command: report

Generate a detailed health report:

codebase-health report [path] [options]

Options:

• --format <format> - Output format: table (default), json, or markdown
• -o, --output <file> - Write report to a file
• -v, --verbose - Show detailed output

Examples:

# Generate markdown report
codebase-health report . --format markdown

# Save detailed JSON report
codebase-health report . --format json -o health-report.json

# Print verbose report
codebase-health report . --verbose

Output Formats

Table Format (Default)

Colored, easy-to-read table with a visual health bar:

╔════════════════════════════════════════╗
║   CODEBASE HEALTH ANALYSIS REPORT     ║
╚════════════════════════════════════════╝

Overall Health Score
████████████████████████████░░          75/100 (Good)

JSON Format

Complete report as structured JSON, perfect for programmatic use:

{
  "repository": "/path/to/repo",
  "overallScore": 75,
  "maxScore": 100,
  "healthStatus": "Good",
  "dimensions": {
    "codeComplexity": { ... },
    "documentation": { ... },
    ...
  }
}

Markdown Format

Human-readable markdown report, great for documentation and sharing:

# Codebase Health Analysis Report

## Overall Score
**75/100** (Good)

## Scoring Breakdown
...

Health Status Interpretation

| Score Range | Status | Meaning | | --- | --- | --- | | 80-100 | Excellent | Well-maintained, healthy codebase | | 60-79 | Good | Solid foundation with room for improvement | | 40-59 | Fair | Notable issues that should be addressed | | 0-39 | Poor | Significant technical debt |

CI/CD Integration

GitHub Actions

name: Health Check
on: [push, pull_request]

jobs:
  health:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - run: npx @glue-tools-ai/codebase-health-score analyze . --format json -o health-report.json
      - uses: actions/upload-artifact@v3
        with:
          name: health-report
          path: health-report.json

GitLab CI

health_check:
  image: node:18
  script:
    - npx @glue-tools-ai/codebase-health-score analyze . --format markdown -o report.md
  artifacts:
    paths:
      - report.md

Performance

• Typically analyzes repositories in 2-5 seconds
• Lightweight - minimal dependencies
• Scalable to large codebases (1000+ files)

Requirements

• Node.js 16.0.0 or higher
• A local Git repository (for full analysis)

Limitations

• Only analyzes directories up to depth 3 by default
• Samples code files for comment ratio estimation
• Git analysis requires a valid .git directory
• Does not perform dynamic code execution or security scanning

Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues.

Built by Glue — AI codebase intelligence for product teams.

License

MIT License - see LICENSE file for details.

Support

• GitHub: glue-tools-ai/codebase-health-score
• Homepage: getglueapp.com
• Email: [email protected]

Version: 1.0.0 Last Updated: 2026-02-16