typescript-metrics

TypeScript code metrics CLI tool - A wrapper for tsg CLI that provides complexity analysis with configurable thresholds, colored output, and CI/CD integration.

Features

• Auto-discovery: Automatically detects TypeScript files via git diff or explicit paths
• Colored Output: Visual indicators (green/yellow/red) for code complexity zones
• Configurable Thresholds: Customize maintainability and complexity limits
• Multiple Output Formats: Human-readable tables or LLM-friendly JSON
• CI/CD Integration: Exit codes for automated quality gates
• Multi-project Support: Handles monorepos with multiple tsconfig files
• Intelligent Filtering: By default, shows only files needing attention (yellow/red zones)

Metrics Analyzed

typescript-metrics analyzes three key complexity metrics:

| Metric | Description | Range | |--------|-------------|-------| | Maintainability Index (MI) | Overall code maintainability | 0-100 (higher is better) | | Cyclomatic Complexity (CC) | Control flow complexity (decision points) | 1+ (lower is better) | | Cognitive Complexity (CoC) | Mental effort to understand code | 1+ (lower is better) |

Installation

Prerequisite: This tool requires typescript-graph (tsg CLI) as a peer dependency.

Global Installation (Recommended)

npm install -g typescript-metrics typescript-graph

Note: The tsm command is available as a shorthand alias for typescript-metrics. Both commands work identically:

typescript-metrics --help    # Full command name
tsm --help           # Shorthand alias (equivalent)

Using npx (No Installation)

# Install tsg globally first (required)
npm install -g typescript-graph

# Then use npx for typescript-metrics
npx typescript-metrics [options] [path...]
# or
npx tsm [options] [path...]

Local Installation

npm install --save-dev typescript-metrics typescript-graph

Then add to your package.json scripts:

{
  "scripts": {
    "metrics": "typescript-metrics",
    "metrics:all": "typescript-metrics --all src/",
    "tsm": "tsm",
    "tsm:all": "tsm --all src/"
  }
}

Quick Start

Tip: Use tsm as a shorthand for typescript-metrics in all examples below.

Analyze Changed Files (Git Diff Mode)

# Analyze only TypeScript files that have changed
typescript-metrics
# or
tsm

Analyze Specific Paths

# Analyze a directory
typescript-metrics src/
# or
tsm src/

# Analyze specific files
typescript-metrics src/utils/date.ts src/helpers/format.ts

# Show all files (disable filtering)
typescript-metrics --all src/

JSON Output for CI/CD

# Output metrics as JSON
typescript-metrics --json src/ > metrics.json
# or
tsm --json src/ > metrics.json

Configuration

Create a .typescript-metrics.rc file in your project root to customize thresholds and tsconfig paths.

Sample Configuration

# .typescript-metrics.rc
# TypeScript configuration directories
TSCONFIGS=(
  "."           # Root project
  "packages/shared"  # Shared library
  "packages/server"  # Backend server
)

# Maintainability Index (MI) - Higher is better
MI_YELLOW_MAX=40    # Yellow zone: <= 40
MI_RED_MAX=20       # Red zone: <= 20

# Cyclomatic Complexity (CC) - Lower is better
CC_YELLOW_MIN=11    # Yellow zone: >= 11
CC_RED_MIN=21       # Red zone: >= 21

# Cognitive Complexity (CoC) - Lower is better
COC_YELLOW_MIN=11   # Yellow zone: >= 11
COC_RED_MIN=21      # Red zone: >= 21

Usage

Command Syntax

typescript-metrics [OPTIONS] [PATH...]

Arguments

| Argument | Description | |----------|-------------| | PATH | Path(s) to analyze. Can be absolute or relative paths. Supports files (.ts) or directories containing .ts files. If omitted, defaults to git diff mode (analyzes changed files only). |

Options

| Option | Description | |--------|-------------| | --help | Show help message and exit | | --all | Show all files (disable yellow/red zone filtering) | | --json | Output metrics as JSON instead of text table | | --red | Show only red-zone files (works with text or JSON output) |

Examples

Git Diff Mode (Default)

# Analyze only changed TypeScript files
typescript-metrics

Directory Analysis

# Analyze specific directory
typescript-metrics src/

# Show all files in directory
typescript-metrics --all src/

# Show only red-zone files (needs immediate attention)
typescript-metrics --red src/

# JSON output for LLM consumption
typescript-metrics --json src/

# JSON output with only red-zone files (for CI gating)
typescript-metrics --red --json src/

File Analysis

# Analyze specific file
typescript-metrics src/utils/date.ts

# Analyze multiple files
typescript-metrics src/utils/date.ts src/helpers/format.ts

CI/CD Integration

# Fail build if red-zone files detected
typescript-metrics --json src/
if [ $? -eq 2 ]; then
  echo "Error: Red-zone files detected!"
  exit 1
fi

Output Formats

Text Table (Default)

Human-readable output with colored status indicators:

FILE                                                     MI      CC    CoC   Status
-----------------------------------------------------  -------  -----  -----  --------
shared/test-lib/ticket/file-ticket-creator.ts          22.77    33     54    RED
shared/test-lib/ticket/ticket-creator.ts               40.88    12     12    YLW
shared/utils/date.ts                                    67.45     5      3    GRN

Column Legend:

• MI: Maintainability Index (0-100, higher is better)
• CC: Cyclomatic Complexity (lower is better)
• CoC: Cognitive Complexity (lower is better)
• Status: Overall health indicator (GRN/YLW/RED)

JSON Format

LLM-friendly JSON output for automated processing:

typescript-metrics --json src/

Output:

{
  "metrics": [
    {
      "filePath": "shared/utils/date.ts",
      "maintainabilityIndex": 67.45,
      "cyclomaticComplexity": 5,
      "cognitiveComplexity": 3,
      "zone": "GRN"
    }
  ]
}

Filtering modes:

• Default: Show yellow + red zones
• --red: Show only red zone
• --all: Show all zones (green + yellow + red)

Exit Codes

| Code | Meaning | Use Case | |------|---------|----------| | 0 | Success (no red-zone files) | Build passes, code quality acceptable | | 1 | Error (invalid arguments, missing dependencies) | Configuration issue, missing tsg CLI | | 2 | Red-zone files detected | CI/CD quality gate failure |

Using Exit Codes in CI/CD

#!/bin/bash
# Example CI/CD script

typescript-metrics --json
EXIT_CODE=$?

if [ $EXIT_CODE -eq 2 ]; then
  echo "❌ Quality gate failed: Red-zone files detected"
  echo "Please refactor high-complexity files before merging."
  exit 1
elif [ $EXIT_CODE -eq 1 ]; then
  echo "❌ Error running metrics check"
  exit 1
else
  echo "✅ Quality gate passed"
fi

Threshold Zones

Maintainability Index (MI)

| Zone | Range | Description | Action | |------|-------|-------------|--------| | Green | ≥ 41 | Well-maintained | No action needed | | Yellow | 21-40 | Moderate concerns | Consider refactoring | | Red | 0-20 | Significant issues | Refactoring required |

Cyclomatic Complexity (CC)

| Zone | Range | Description | Action | |------|-------|-------------|--------| | Green | ≤ 10 | Simple control flow | No action needed | | Yellow | 11-20 | Moderately complex | Consider simplifying | | Red | ≥ 21 | Highly complex | Refactoring required |

Cognitive Complexity (CoC)

| Zone | Range | Description | Action | |------|-------|-------------|--------| | Green | ≤ 10 | Easy to understand | No action needed | | Yellow | 11-20 | Moderate effort | Consider simplifying | | Red | ≥ 21 | Difficult to understand | Refactoring required |

CI/CD Integration

GitHub Actions

name: Code Quality Check

on:
  pull_request:
    paths:
      - '**.ts'
      - '**.tsx'

jobs:
  metrics:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: npm install -g typescript-graph
      - run: npx typescript-metrics --json
        # Exit code 2 (red-zone files) will fail the workflow

Dependencies

• typescript-graph (tsg CLI): Core TypeScript analysis engine
• jq: JSON processing (for text table formatting)

Installing Dependencies

# Install tsg (required)
npm install -g typescript-graph

# Install jq (required on macOS/Linux)
# macOS
brew install jq

# Linux (Debian/Ubuntu)
sudo apt-get install jq

# Linux (RHEL/CentOS)
sudo yum install jq

Error Handling

| Error | Cause | Solution | |-------|-------|----------| | tsg: command not found | typescript-graph not installed | Run npm install -g typescript-graph | | Cannot find tsconfig | Missing tsconfig.json | Create tsconfig.json or update .typescript-metrics.rc | | No TypeScript files changed | No .ts files in git diff | Modify a .ts file or provide explicit path | | Path does not exist | Invalid path argument | Check path spelling and location |

Recipes

Find Most Complex Files

typescript-metrics --all --json | \
  jq -r '.metrics | sort_by(.maintainabilityIndex) | .[] | "\(.filePath): \(.maintainabilityIndex)"'

Integration with LLMs

# Feed metrics to Claude, GPT-4, etc.
typescript-metrics --json src/ | \
  jq -r '.metrics[] | "File: \(.filePath)\nMI: \(.maintainabilityIndex), CC: \(.cyclomaticComplexity)\n"' | \
  llm "Review these files and suggest refactoring"

Architecture

See docs/ARCHITECTURE.md for implementation details.

License

MIT

Contributing

Contributions welcome! Please open an issue or submit a pull request.

Related Projects

• typescript-graph - TypeScript code analysis and dependency visualization tool

Support

• Issues: Report bugs and feature requests on GitHub
• Documentation: See inline help: typescript-metrics --help