npm package: @glue-tools-ai/codebase-health-score
Description: Calculate a health score for any Git repository. Analyzes code complexity, documentation coverage, test presence, dependency health, and contributor patterns.
Author: Glue
Latest version: 1.0.0

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

[![npm version](https://img.shields.io/npm/v/@glue-tools-ai/codebase-health-score.svg)](https://www.npmjs.com/package/@glue-tools-ai/codebase-health-score)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js version](https://img.shields.io/node/v/@glue-tools-ai/codebase-health-score.svg)](https://nodejs.org/)

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:

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

### Global Installation

Install globally for repeated use:

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

### Local Installation

Install in a project:

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

## Quick Start

### Basic Analysis

Analyze the current repository:

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

### Analyze Another Repository

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

### Generate Detailed Report

```bash
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:

```bash
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:**

```bash
# 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:

```bash
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:**

```bash
# 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:

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

### Markdown Format

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

```markdown
# 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

```yaml
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

```yaml
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](https://getglueapp.com) — AI codebase intelligence for product teams.

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Support

- GitHub: [glue-tools-ai/codebase-health-score](https://github.com/glue-tools-ai/codebase-health-score)
- Homepage: [getglueapp.com](https://getglueapp.com)
- Email: [hello@getglueapp.com](mailto:hello@getglueapp.com)

---

**Version:** 1.0.0
**Last Updated:** 2026-02-16