@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: hello@getglueapp.com

Version: 1.0.0 Last Updated: 2026-02-16

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
bin		bin
src		src
test		test
.gitignore		.gitignore
.npmignore		.npmignore
LICENSE		LICENSE
README.md		README.md
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

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

Features

Installation

Using npx (Recommended)

Global Installation

Local Installation

Quick Start

Basic Analysis

Analyze Another Repository

Generate Detailed Report

Sample Output

Scoring Dimensions

Code Complexity (25 points)

Documentation (20 points)

Test Coverage (20 points)

Dependency Health (15 points)

Git Health (20 points)

Usage

Command: analyze

Command: report

Output Formats

Table Format (Default)

JSON Format

Markdown Format

Health Status Interpretation

CI/CD Integration

GitHub Actions

GitLab CI

Performance

Requirements

Limitations

Contributing

License

Support

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages