Code Evolution Visualizer 📈

code-evolution is a premium CLI tool that analyzes a project's Git history and generates rich visual insights about how the codebase evolved over time.

Instead of showing raw commits and line-by-line diffs, it tells the architectural growth story of your repository.

✨ Features

• Project Growth Analysis: Track file count and lines of code (LOC) over time.
• Module Evolution Tracking: Detect which directories/modules are growing the fastest.
• Complexity Tracking: Estimates cyclomatic complexity, function count, and dependency density to flag technical debt growth.
• Hotspot Detection: Identifies the most frequently changed components in history.
• Terminal Visualizations: Self-scaling Unicode block charts rendered directly in your terminal—no browser required.
• Story Mode (--story): Tells a narrative story of the codebase's history month-by-month.
• Year in Review (--year-in-review): Generates annual review stats (commits, files, LOC, largest coding day, productive month).
• Interactive HTML Reports (--html): Outputs a single, portable, fully styled interactive dashboard using Chart.js.

🚀 Installation

You can run the tool directly using npx:

npx code-evolution .

Or install it globally:

npm install -g code-evolution

📖 Usage & Options

Run the CLI tool inside a Git repository or specify a repository path:

code-evolution [path]

Options

| Option | Shortcut | Description | |:---|:---|:---| | --story | -s | Generate a chronological narrative summary of milestones. | | --year-in-review [year] | -y [year] | Generate a yearly review summary (defaults to last active year). | | --html | | Generate a standalone interactive HTML report (evolution-report.html). | | --help | -h | Display help text. | | --version | -v | Display package version. |

🎨 Examples

Standard Report

code-evolution .

📈 Project Evolution Report

Project Age: 14 months

Files
  Jan 2025 : 12
  Jun 2025 : 58
  Dec 2025 : 145

Lines of Code
  2,100 → 28,450

Top Growth Areas
  1. auth/        +420%
  2. payments/    +310%
  3. api/         +220%

Most Active Month
  Oct 2025 (84 commits)

Most Changed File
  src/auth/login.ts (45 commits)

Story Mode

code-evolution . --story

📖 Your Project Story

Jan 2025
  Project created 🚀
  │
Feb 2025
  Authentication and user flow introduced 🔐
  │
Apr 2025
  API endpoints and routing established 🌐
  │
Aug 2025
  Testing effort begins! Unit tests introduced 🧪

📂 Project Structure

src/
  commands/
    analyze.js        # Main CLI reporters (Standard & Year in Review)
    html.js           # standalone interactive HTML template builder
    story.js          # Milestones rule-based engine
  analyzers/
    codeAnalyzer.js   # Fast, AST-free complexity & logical LOC parser
    gitAnalyzer.js    # simple-git wrapper for commits and tree snapshots
    growthAnalyzer.js # Timeline snapshots aggregator
    complexityAnalyzer.js # Complexity trend statistics
    coverageAnalyzer.js # Test suite files metrics
  visualizers/
    terminalChart.js  # Unicode block charts with Chalk colors
  utils/
    fileUtils.js      # Ignored file patterns & path mapping utilities

🔒 License

ISC License.