What is CommitLens?

Most teams treat git history as a log. CommitLens treats it as a data source.

It parses your repository's commit history and runs 15 different analyzers to surface patterns you'd never find manually — files trending toward instability, developers working unsustainable hours, knowledge silos forming quietly, and modules growing too complex to maintain safely.

No config files. No databases. Just point it at any git repo and get answers.

npx commit-lens --summary

  Sprint Health Report
  ────────────────────────────────────────
  Stability:     7.2/10
  Risk:          MODERATE
  Burnout:       Low
  Velocity:      Stable
  Quality:       8.4/10
  Collaboration: 6.1/10

Installation

npm install -g commit-lens

Or run directly without installing:

npx commit-lens --help

Usage

Run any command inside a git repository:

commitlens --predict          # Which files are trending toward instability?
commitlens --burnout          # Who's working late nights and weekends?
commitlens --ownership        # Where has ownership silently shifted?
commitlens --stale            # What files haven't been touched in months?
commitlens --quality          # How good are our commit messages really?
commitlens --complexity       # Which modules carry the most risk?
commitlens --dependency-risk  # What breaks everything when it changes?
commitlens --summary          # One-page health report for the sprint
commitlens --insights         # Human-readable analysis of the full picture
commitlens --test-risk        # Which files are probably untested?
commitlens --dev "alice"      # Deep-dive on a specific contributor
commitlens --simulate "alice" # What happens if Alice leaves the team?
commitlens --collaboration    # How well is work distributed?
commitlens --export json      # Dump results to a JSON file
commitlens --export html      # Generate a self-contained HTML dashboard
commitlens --ci               # Exit code 1 if risk thresholds are exceeded

Features in Detail

Predictive Risk Analysis

Runs linear regression on per-file churn over rolling weekly windows. Instead of telling you what's already broken, it flags files that are accelerating toward instability.

commitlens --predict

  File                  Trend        ETA       Churn   Contributors
  payment.js            increasing   7 days    842     4
  auth/session.js       increasing   14 days   531     3

Files with increasing churn velocity get flagged with an estimated time-to-instability.

Developer Burnout Detector

Analyzes commit timestamps to detect unsustainable work patterns. Looks for:

• Commits after 10pm or before 6am
• Weekend activity and consecutive weekend streaks
• Sudden spikes in daily commit volume

commitlens --burnout

  Arjun — Risk: high
     42% commits after midnight
     Working 6 consecutive weekends

Code Ownership Drift

Compares the first half and second half of each file's commit history to detect ownership changes. Catches both healthy knowledge transfer and chaotic fragmentation.

commitlens --ownership

  auth.js       ownership shifted from Rahul → 4 devs
  config.js     consolidated to Priya

Stale File Detection

Surfaces files that haven't been modified in 90+ days (configurable). Useful for identifying dead code, abandoned experiments, or files that need cleanup.

commitlens --stale

  utils/oldParser.js     182 days    last: 2025-09-01
  legacy/mailer.js       340 days    last: 2025-04-15

Commit Quality Analysis

Scans commit messages against known low-quality patterns (fix, temp, asdf, single-character messages) and flags oversized commits that touch too many files.

commitlens --quality

  Total commits: 1,247
  Low quality:   312 (25%)
  Avg files/commit: 8.3
  Large commits: 41 detected

Module Complexity Score

Computes a weighted composite score (0-10) from four dimensions:

| Weight | Dimension | |--------|-----------| | 35% | Churn (total lines added + deleted) | | 25% | Commit frequency | | 20% | Number of distinct contributors | | 20% | File size (estimated from total additions) |

commitlens --complexity

  checkout/index.js      9.2/10    churn: 2841   authors: 7
  api/gateway.js         8.1/10    churn: 1923   authors: 5

Dependency Risk Scanner

Builds a lightweight import graph by scanning require() and import statements across all tracked files. Cross-references with churn data to find files that are both volatile and widely depended upon — the most dangerous combination.

commitlens --dependency-risk

  db/connection.js    churn: 412    imported by: 23 files    risk: 8.7/10

Sprint Health Summary

Aggregates all analyzers into a single dashboard. Stability is derived from predictive risk, burnout from timestamp analysis, velocity from commit rate trends, and quality from message analysis.

commitlens --summary

AI Insights

Generates context-aware, human-readable paragraphs by interpreting patterns across all analyzers. No LLM required — it's rule-based pattern matching that produces targeted recommendations.

commitlens --insights

  [Architecture] Your api/ module is becoming a bottleneck with 6
  high-complexity files. Consider breaking it into smaller modules.

  [Team Health] Arjun is showing signs of burnout. Consider
  workload redistribution.

  [Knowledge] 38% of files have single-developer ownership.
  Consider redistributing knowledge across team members.

Test Coverage Proxy

No test runner needed. Uses churn volatility (coefficient of variation) and test file presence as heuristics to estimate which files are likely undertested.

commitlens --test-risk

Developer Profile

Generates a stat card for any contributor — their top modules, typical working hours, commit quality, and overall risk level.

commitlens --dev "alice"

  Alice Chen
  ────────────────────────────────────────
  Commits:       247
  Files owned:   89
  Peak time:     afternoon
  Late night:    8%
  Risk:          low
  Top modules:
    frontend/components (23 files)
    shared/utils (12 files)

Team Loss Simulator

Simulates a developer's departure by recalculating bus factor and identifying files that would become orphaned or dangerously under-maintained.

commitlens --simulate "alice"

  If Alice leaves:
  - 12 files become high-risk
  - 3 files become completely orphaned
  - frontend/ bus factor drops to 1

Team Collaboration Score

Quantifies how well work is distributed using four metrics:

| Metric | What it measures | |--------|-----------------| | Distribution (Shannon entropy) | Are commits spread evenly across developers? | | Co-authorship rate | What percentage of files have multiple contributors? | | Cross-module reach | Do developers work across module boundaries? | | Gini coefficient | How equal is the commit distribution? |

commitlens --collaboration

Export

Dump any analysis to JSON for CI integration or generate a self-contained HTML dashboard for sharing with non-technical stakeholders.

commitlens --export json     # writes commitlens-report-YYYY-MM-DD.json
commitlens --export html     # writes commitlens-report-YYYY-MM-DD.html

The HTML report uses a dark-themed responsive layout that works without any external dependencies.

CI Integration

Use in your CI pipeline to fail builds when risk thresholds are exceeded. Exits with code 1 if it detects critical instability, extreme complexity, or poor commit quality.

commitlens --ci

Add to your pipeline:

# GitHub Actions example
- name: CommitLens Health Check
  run: npx commit-lens --ci

Architecture

commitlens.js                CLI entry point (Commander.js)
src/
  cli/
    runner.js                Routes flags to analyzers, manages output
  core/
    reader.js                Git data ingestion via simple-git
    parser.js                Transforms raw logs into structured data
  analyzers/
    predict.js               Linear regression on churn windows
    burnout.js               Timestamp pattern analysis
    ownershipDrift.js         First-half vs second-half ownership comparison
    staleFiles.js             Last-modified threshold detection
    commitQuality.js          Regex-based message quality scoring
    complexity.js             Weighted composite scoring
    dependencyRisk.js         Import graph + churn cross-reference
    sprintHealth.js           Multi-signal aggregation
    insights.js               Rule-based insight generation
    testRisk.js               Churn volatility + test file heuristic
    devProfile.js             Per-developer stat aggregation
    simulate.js               Bus factor recalculation
    collaboration.js          Entropy + Gini-based scoring
    churn.js                  Shared churn computation
    busFactor.js              Shared bus factor computation
  output/
    terminal.js              Chalk + cli-table3 rendering
    json.js                  JSON file export
    html.js                  Self-contained HTML dashboard
    ci.js                    Exit code logic for pipelines

Dependencies

| Package | Purpose | |---------|---------| | simple-git | Git log extraction | | commander | CLI flag parsing | | chalk | Terminal coloring | | cli-table3 | Table formatting | | ora | Loading spinners |

No runtime dependencies beyond these five packages.

Contributing

Issues and pull requests are welcome. If you find a bug or have an idea for a new analyzer, open an issue on GitHub.

License

MIT