Skip to content

Hybriant/codestat

BranchesTags

Repository files navigation

CodeStat

Beautiful CLI tool to analyze project composition and count lines of code with GitHub-inspired colors

npm version Node.js Version License: MIT Code Quality Security CI CD

Stars Forks Issues

Transform your code analysis experience with stunning visuals and powerful insights

Chinese README: README_CN.md

Features

Beautiful Visual Output

  • GitHub-inspired colors for 93+ programming languages
  • Rich terminal output with ASCII art and progress bars
  • Responsive design that adapts to your terminal size
  • Multiple output formats: Fancy, Simple, and JSON

Performance & Intelligence

  • Lightning fast with async directory traversal
  • Smart caching for instant repeated analyses
  • Real-time progress tracking with beautiful spinners
  • Streaming support for large files (10MB+)

Advanced Analytics

  • Gamified experience with milestones and achievements
  • Analysis history with growth trends
  • Change comparison between analyses
  • Detailed insights including largest files and language distribution

Flexible & Extensible

  • Configuration files for project-specific settings
  • Quick analysis mode for rapid feedback
  • Multi-platform support (Linux, macOS, Windows)
  • Lightweight with minimal dependencies

Quick Start

Installation

# Install globally (recommended)
npm install -g codestat

# Or use npx
npx codestat --help

Basic Usage

# Analyze current directory
codestat analyze

# Quick analysis
codestat quick

# Analyze specific path
codestat analyze /path/to/project

# Analyze a single file
codestat file ./src/index.js

# Initialize config file
codestat config --init

# Get help
codestat --help

Showcase

Basic Analysis

$ codestat analyze
╭ CODE ANALYSIS ENGINE ╮
╠══════════════════════════════════════════════════════════╣

[STA] SUMMARY STATISTICS
┌─────────────────────────────────────────────────────────────┐
│ Total Files     :     42                              │
│ Directories     :     12                              │
│ Total Lines     :  8,247                              │
│ Code Lines      :  6,183                              │
│ Comments        :  1,247                              │
│ Blank Lines     :    817                              │
└─────────────────────────────────────────────────────────────┘

[TYP] FILE TYPE ANALYSIS
┌─────────┬───────┬──────────┬──────┬──────────┬───────┐
│ Type    │ Files │   Lines  │ Code │ Comments │ Blank │
├─────────┼───────┼──────────┼──────┼──────────┼───────┤
│ JS      │    24 │    5,234 │ 4123 │      847 │   264 │
│ TS      │     8 │    1,847 │ 1523 │      234 │    90 │
│ JSON    │     6 │      892 │  892 │        0 │     0 │
│ MD      │     4 │      274 │  145 │        0 │   129 │
└─────────┴───────┴──────────┴──────┴──────────┴───────┘

Quick Analysis

$ codestat quick
╭ QUICK ANALYSIS ╮
╠════════════════════════════════════════════════════╣
│ Files         :     42                      │
│ Total Lines   :  8,247                      │
│ Code Lines    :  6,183                      │
│ Avg Lines/File:    196                      │
╚════════════════════════════════════════════════════╝

Statistics & Achievements

$ codestat stats
╭ CODESTAT STATISTICS ╮
╠════════════════════════════════════════════════════╣

[STA] YOUR CODING JOURNEY
┌─────────────────────────────────────────────────────┐
│ Projects Analyzed:   12                          │
│ Files Analyzed:      1,247                       │
│ Lines of Code:      89,247                       │
│ Analyses Completed:  156                          │
└─────────────────────────────────────────────────────┘

[ACH] RECENT ACHIEVEMENTS
┌─────────────────────────────────────────────────────┐
│ 🏆 100K Lines Analyzed!                    │
│ ⭐ 50 Projects Analyzed                     │
│ ⭐ 1000 Files Analyzed                      │
└─────────────────────────────────────────────────────┘

Advanced Usage

Configuration File

Create a .codestatrc file in your project root:

{
  "extensions": ["js", "ts", "jsx", "tsx", "py", "java"],
  "ignore": ["node_modules", ".git", "dist", "build"],
  "maxFileSize": "10MB",
  "output": "fancy",
  "quiet": false,
  "showHidden": false,
  "skipBinaryFiles": true
}

Command Options

# Custom extensions
codestat analyze -e "js,ts,py,java"

# Ignore patterns
codestat analyze -i "node_modules,.git,dist"

# JSON output
codestat analyze --json > results.json

# Quiet mode
codestat analyze --quiet

# Clear cache
codestat analyze --clear-cache

# Simple output
codestat analyze -o simple

All Commands

# Analyze directory
codestat analyze [path] [options]

# Quick analysis
codestat quick [path]

# Analyze single file
codestat file <file>

# Cache management
codestat cache --stats
codestat cache --clear

# Your statistics
codestat stats

# Project history
codestat history [path]

# Configuration
codestat config --init
codestat config --show

Supported Languages

CodeStat supports 93 programming languages and file types including:

Popular Languages

  • JavaScript/TypeScript (.js, .ts, .jsx, .tsx)
  • Python (.py)
  • Java (.java)
  • C/C++ (.c, .cpp, .h)
  • Go (.go)
  • Rust (.rs)
  • PHP (.php)
  • Ruby (.rb)
  • C# (.cs)
  • Swift (.swift)
  • Kotlin (.kt)
  • Scala (.scala)

Web Technologies

  • HTML (.html, .htm)
  • CSS (.css, .scss, .sass, .less)
  • Vue (.vue)
  • Svelte (.svelte)
  • React (.jsx, .tsx)

Data & Configuration

  • JSON (.json)
  • YAML (.yaml, .yml)
  • TOML (.toml)
  • XML (.xml)
  • SQL (.sql)

And Many More...

  • Shell scripts, Dockerfiles, Markdown, LaTeX, Assembly, and more!

Output Formats

Fancy Output (Default)

Beautiful ASCII art with colors and progress bars

Simple Output

Clean, minimal output perfect for scripts

JSON Output

Machine-readable format for integration:

{
  "totalFiles": 42,
  "totalLines": 8247,
  "codeLines": 6183,
  "commentLines": 1247,
  "blankLines": 817,
  "byFileType": {
    "js": {
      "files": 24,
      "totalLines": 5234,
      "codeLines": 4123,
      "commentLines": 847,
      "blankLines": 264
    }
  },
  "largestFiles": [
    {
      "path": "src/analyzer.js",
      "lines": 764,
      "type": "js"
    }
  ]
}

Gamification Features

Milestones & Achievements

  • Lines Analyzed: Track your coding journey
  • Files Analyzed: Monitor file processing
  • Projects Analyzed: Count unique projects
  • Cache Efficiency: Track performance optimization

Progress Tracking

  • Real-time progress indicators
  • Achievement notifications
  • Personal statistics dashboard
  • Historical growth trends

API Usage

Use CodeStat as a Node.js module:

const { analyzeProject } = require('codestat');

// Basic analysis
const results = await analyzeProject('/path/to/project', ['js', 'ts'], ['node_modules']);
console.log(results);

// Advanced options
const detailedResults = await analyzeProject(
  '/path/to/project',
  ['js', 'ts', 'py'],
  ['node_modules', '.git'],
  {
    maxFileSize: 1024 * 1024 * 10, // 10MB
    verbose: true,
    useCache: true,
    progressCallback: (progress) => {
      console.log(`Progress: ${progress.progress}%`);
    }
  }
);

Development

Setup

git clone https://github.com/Hybriant/codestat.git
cd codestat
npm install
npm run install-global

Testing

# Run all tests
npm test

# Run specific test suites
npm run test:analyzer
npm run test:cli
npm run test:language

Scripts

# Development
npm run dev

# Lint (auto-fix)
npm run lint

# Lint check (CI-friendly)
npm run lint:check

# Security test
npm run test:security

# Build (no-op in current version)
npm run build

Performance Features

Intelligent Caching

  • Automatic caching of analysis results
  • Cache invalidation on file changes
  • TTL-based expiration (24 hours)
  • Size management (100 entries max)

Large File Support

  • Streaming analysis for files > 1MB
  • Memory-efficient processing
  • Configurable size limits
  • Binary file detection

Security Features

  • Path traversal protection
  • Input sanitization
  • Command injection prevention
  • Safe file operations

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Roadmap

  • Web Interface - Beautiful web dashboard
  • Git Integration - Blame, history, and commit analysis
  • Real-time Monitoring - Watch files as they change
  • Advanced Metrics - Complexity, maintainability, technical debt
  • Plugin System - Custom analyzers and formatters
  • Database Export - Save results to databases
  • CI/CD Integration - GitHub Actions, GitLab CI
  • Team Features - Collaborative analysis and sharing

Troubleshooting

Common Issues

Permission Denied

# Ensure read permissions
chmod -R +r /path/to/project

Large Files

# Increase file size limit
codestat analyze --max-size 50MB

Memory Issues

# Exclude large directories
codestat analyze -i "node_modules,.git,dist,build"

Getting Help

# Command help
codestat --help
codestat analyze --help

# Cache info
codestat cache --stats

# Configuration help
codestat config --show

License

MIT License - see LICENSE file for details.

Acknowledgments

  • GitHub for the color scheme inspiration
  • Node.js community for the amazing ecosystem
  • All contributors who helped make CodeStat better

Support

Star us on GitHub if you find CodeStat useful!

About

A CLI tool written in Node.js

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages