TypeScript code quality analyzer that runs 100% locally. Get actionable metrics in seconds without sending any code to the cloud.
- ✨ Features
- 🚀 Quick Start
- 📋 Requirements
- 📊 Example Output
- 📐 How It Works
- 🎯 Production Code Analysis
- 🔧 CLI Options
- 📚 Best Practices
- 🗺️ Roadmap
- 🤝 Contributing
- 📈 Why InsightCode?
- 🙏 Acknowledgments
- 📝 License
- 🔗 Links
- 🔒 100% Local - Your code never leaves your machine
- ⚡ Fast - Proven on large codebases (analyzes over 40,000 lines/sec)
- 🧠 Criticality-Aware Scoring - Prioritizes issues based on file complexity and its architectural impact.
- 🎯 Actionable Metrics - Focus on what matters: complexity, duplication, maintainability, and reliability.
- 🧬 Rich Context for LLM Analysis - Provides detailed architectural insights to help LLMs better understand and analyze code structure.
- 🎨 Beautiful Output - Clear, colorful terminal reports.
# Install globally
npm install -g insightcode-cli
# Simple analysis (new default behavior)
insightcode
# Analyze specific path
insightcode ./src
# Focus on production code only
insightcode --production
# Use industry-standard strict duplication thresholds
insightcode --strict-duplication
# Export for CI/CD integration
insightcode --json > report.json
# Multiple format options
insightcode --format=summary # Brief overview
insightcode --format=critical # Only critical files
insightcode --format=ci # CI/CD friendly output- Node.js 18.0 or higher
- TypeScript/JavaScript projects
Real analysis of the Angular project using insightcode --production ./angular/packages:
🔍 Analyzing code quality...
📁 Found 4282 files
📊 Extracting file details...
⚙️ Processing metrics...
📈 Calculating overview...
┌────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ packages vlatest (local, 0 stars) │
│ Analysis from Jul 25, 2025, took 0.0s │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
┌──────────────────────────┬────────────────────────────────────────────────────────────────────┬────────────┐
│ OVERVIEW: GRADE B (85) │ 1174 critical files found requiring attention │ │
├──────────────────────────┼────────────────────────────────────────────────────────────────────┼────────────┤
│ Complexity │ ██████████████████████████████████████████████████░░░░░░░░░░░░░░ │ 78 │
│ │ │ │
│ Duplication │ █████████████████████████████████████████████████████████████░░░ │ 96 (5%) │
│ │ │ │
│ Maintainability │ ██████████████████████████████████████████████████████░░░░░░░░░░ │ 85 │
└──────────────────────────┴────────────────────────────────────────────────────────────────────┴────────────┘
┌─────────────────────────────────────────────────────┬──────────────────────────────────────────────────────┐
│ KEY STATS │ BUSINESS IMPACT │
├─────────────────────────────────────────────────────┼──────────────────────────────────────────────────────┤
│ Total Files 4282 │ 🚨 High Maintenance Cost 885 │
│ Total LOC 582k │ 🐌 Slow to Change Files 556 │
│ Avg Complexity 10.7 │ 🔗 Tightly Coupled Files 783 │
└─────────────────────────────────────────────────────┴──────────────────────────────────────────────────────┘
┌ CRITICAL FILES REQUIRING ATTENTION ────────────────────────────────────────────────────────────────────────┐
│ S │ File Path │ Metrics │ Primary Issue │
├────┼────────────────────────────────────────────────┼───────────────────────┼──────────────────────────────┤
│ 0 │ common/locales/closure-locale.ts │ C: 548 D: 0% L: 1k │ 💀 complexity (critical) │
│ 0 │ compiler-cli/.../type_check_block.ts │ C: 451 D: 0% L: 2k │ 💀 complexity (critical) │
│ 0 │ compiler/src/output/output_ast.ts │ C: 391 D: 0% L: 2k │ 💀 complexity (critical) │
│ 0 │ compiler/src/ml_parser/lexer.ts │ C: 322 D: 8% L: 1k │ 💀 complexity (critical) │
│ 0 │ compiler/.../expression.ts │ C: 311 D: 0% L: 1k │ 💀 complexity (critical) │
│ 0 │ compiler-cli/.../handler.ts │ C: 306 D: 0% L: 2k │ 💀 complexity (critical) │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
DEEP DIVE: KEY FUNCTION ANALYSIS
──────────────────────────────────────────────────────────────────────────────────────────────────────────────
🎯 reifyCreateOperations in compiler/src/template/pipeline/src/phases/reify.ts
Metrics: Complexity: 86 | Lines: 359 | Params: 2
Detected Issues:
- critical-complexity (critical) : Severely impacts maintainability
- long-function (high) : Should be split into smaller functions
- deep-nesting (medium) : Hard to read and test
- multiple-responsibilities (medium): Clean separation of concerns
· · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · ·
🎯 resolve in compiler-cli/.../handler.ts
Metrics: Complexity: 84 | Lines: 501 | Params: 3
Detected Issues:
- critical-complexity (critical) : Severely impacts maintainability
- long-function (high) : Should be split into smaller functions
- multiple-responsibilities (high): Clean separation of concerns
- deep-nesting (medium) : Hard to read and test
- impure-function (low) : Side effects make testing harder
· · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · ·
🎯 getDateFormatter in common/src/i18n/format_date.ts
Metrics: Complexity: 82 | Lines: 309 | Params: 1
Detected Issues:
- critical-complexity (critical) : Severely impacts maintainability
- long-function (high) : Should be split into smaller functions
- multiple-responsibilities (medium): Clean separation of concerns
· · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · ·
🎯 transformExpressionsInOp in compiler/.../expression.ts
Metrics: Complexity: 72 | Lines: 152 | Params: 3
Detected Issues:
- critical-complexity (critical) : Severely impacts maintainability
- long-function (high) : Should be split into smaller functions
- multiple-responsibilities (high): Clean separation of concerns
- deep-nesting (medium) : Hard to read and test
· · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · ·
🎯 analyze in compiler-cli/.../handler.ts
Metrics: Complexity: 59 | Lines: 487 | Params: 2
Detected Issues:
- critical-complexity (critical) : Severely impacts maintainability
- long-function (high) : Should be split into smaller functions
- god-function (high) : Violates Single Responsibility
- multiple-responsibilities (high): Clean separation of concerns
- deep-nesting (medium) : Hard to read and test
- impure-function (low) : Side effects make testing harder
InsightCode's analysis is built on a "criticality-first" philosophy. It first measures the fundamentals in each file, then uses project-wide context to weigh them based on their actual importance.
Counts decision points in your code. Based on McCabe's complexity metric (extended to include logical operators):
- Base complexity: Every file starts at 1
- +1 for each:
if,else if,for,while,switch case,catch,&&,||,? : - Target: ≤ 10 excellent, ≤ 15 good
function validate(user) { // Base: 1
if (!user) return false; // +1 for if
if (user.age < 18) return false; // +1 for if
return user.active && user.verified; // +1 for &&
} // Total: 4Detects actual copy-paste duplication using pragmatic content analysis:
- Algorithm: 8-line sliding window with normalization
- Philosophy: Focus on refactorable duplication, not structural patterns
- Target: < 3% excellent, < 8% good
Composite score based on file size and function density:
- File size: ≤ 200 lines excellent, ≤ 300 good
- Function count: ≤ 10 per file excellent, ≤ 15 good
- Extreme penalty: Files > 1000 lines get additional penalties
Measures potential defects and code quality issues:
- Based on detected issues: Deep nesting, long functions, complex conditions
- Issue severity weighting: Critical issues have higher impact
- Function-level analysis: Aggregates issues across all functions
- Lower score indicates: Higher risk of bugs and maintenance problems
The final project score is a weighted average across four dimensions (complexity, duplication, maintainability, reliability), with individual file scores weighted by criticality.
Instead of a fixed weight, the weight of each file is determined by its Criticality Score. This score is calculated from the file's own complexity combined with its Impact—how many other files in the project depend on it.
This means issues in important, highly-connected files will affect your final grade more, guiding you to fix what truly matters.
InsightCode uses graduated thresholds aligned with industry standards:
| Grade | Score | What it means |
|---|---|---|
| A | 90-100 | Exceptional! Keep it up |
| B | 80-89 | Good, minor improvements possible |
| C | 70-79 | Fair, consider refactoring |
| D | 60-69 | Poor, needs attention |
| F | 0-59 | Critical, major refactoring needed |
Real-World Context: Based on our analysis of 9 popular projects:
- Grade B: Small, focused libraries (uuid, chalk).
- Grade D: Large projects with significant duplication (jest).
- Grade F: Complex frameworks, compilers, or linters (react, typescript, vue, eslint).
A low score doesn't mean the code is "bad," but that it presents significant maintenance challenges according to our metrics.
Different file types have different standards:
| File Type | Complexity | File Size | Duplication |
|---|---|---|---|
| Production | ≤10 / ≤20 | ≤200 / ≤300 | ≤15% / ≤30% |
| Test Files | ≤15 / ≤30 | ≤300 / ≤500 | ≤25% / ≤50% |
| Examples | ≤20 / ≤40 | ≤150 / ≤250 | ≤50% / ≤80% |
Format: Medium threshold / High threshold
Focus on what matters - your actual product code:
# Analyze only production code
insightcode --production
# This excludes:
# - Test files (**/test/**, *.spec.ts, *.test.js)
# - Example code (**/examples/**, **/demo/**)
# - Scripts & tools (**/scripts/**, **/tools/**)
# - Fixtures & mocks (**/fixtures/**, **/mocks/**)
# - Benchmark files (**/benchmark/**)Test files and examples often have acceptable duplication and complexity that can mask real issues:
| Project | Full Codebase Analysis | Production Only | Impact |
|---|---|---|---|
| Chalk | A (96) | B (82) | Core is more complex than it appears |
| TypeScript | C (76) | F (28) | Massive algorithmic complexity in compiler |
| Commander | C (80) | F (54) | Command parsing logic needs refactoring |
The production-only analysis gives you the true picture of your codebase health.
# Analysis modes
insightcode # Default: analyze current directory
insightcode ./src # Analyze specific path
insightcode --production # Focus on production code only
# Duplication analysis modes (v0.6.0+)
insightcode --strict-duplication # Industry standards (3%/8%/15%)
insightcode # Legacy mode (15%/30%/50%) - default
# Output formats
insightcode --json # Full JSON output
insightcode --format=summary # Brief overview
insightcode --format=critical # Only critical files
insightcode --format=ci # CI/CD optimized output
insightcode --format=markdown # Markdown report
# Filtering
insightcode --exclude "**/*.spec.ts" --exclude "**/vendor/**"
# Get help
insightcode --helpChoose the appropriate duplication analysis mode for your project context:
| Mode | Thresholds | Best For | Example Usage |
|---|---|---|---|
| Legacy (default) | 15%/30%/50% | Existing codebases, gradual improvement | insightcode |
| Strict | 3%/8%/15% | New projects, industry alignment | insightcode --strict-duplication |
Strict mode aligns with industry standards (SonarQube, Google, etc.) while Legacy mode provides more permissive thresholds suitable for brownfield projects.
The --json flag outputs comprehensive analysis results in a structured format.
- Start with production code: Use
--productionto focus on what matters - Track trends: Run regularly and monitor score changes over time
- Focus on top issues: The tool shows the 5 most critical files - start there
- Consider context: High complexity might be justified (algorithms, parsers)
📖 Complete Guide: How to Use Code Quality Scores Wisely
| Your Score | What It Means | Action |
|---|---|---|
| A (90-100) | Excellent code quality | Maintain standards |
| B (80-89) | Good, production-ready | Monitor complexity growth |
| C (70-79) | Typical active project | Review top 5 issues |
| D-F (0-69) | Needs attention | Check if justified or refactor |
- 🔍 Enhanced Function-Level Analysis: Better complexity breakdown with severity-based sorting to identify the most critical functions
- 🎯 Strict Duplication Mode: New
--strict-duplicationflag for industry-standard thresholds (3%/8%/15%) - 📊 Improved Reports: Better insights and findings presentation with function-level critical issue tracking
- 📚 New Documentation: Comprehensive CriticismScore guide to help understand project scoring methodology
- 📈 Updated Benchmarks: Fresh analysis data across popular open-source projects for better context
- 🚨 CLI Interface Redesign: Analysis is now the default action -
analyzesubcommand removed - 🚨 Flag Renaming:
--exclude-utility→--productionfor better clarity - 🚨 Removed Features:
--with-contextflag no longer available - 📚 Complete Documentation Audit: All technical documentation synchronized with implementation (79+ examples validated)
- 🔍 Dual-Mode Duplication Analysis: Choose between strict (industry standards) and legacy (permissive) thresholds
- ⚡ Enhanced Developer Experience: Added
npm run typecheck, improved error handling, unified validation tools - 🎯 Mathematical Validation: Every scoring formula and constant verified for 100% accuracy
- 🛡️ Quality Assurance: Comprehensive validation system prevents documentation drift
- Rich Context Extraction: Detailed architectural insights for LLM analysis and external tools
- Enhanced Function Analysis: Deep complexity breakdown with pattern detection
- Comprehensive Code Context: Analysis of async patterns, error handling, TypeScript usage
- Advanced Criticality Engine: Scoring weighted by file complexity and architectural impact
- Architectural Metrics: High-impact file detection and complexity distribution analysis
- Enhanced JSON Output: Complete metrics exposure for CI/CD and external tools
- Academic Methodology: Research-based best practices for metric aggregation
- Enhanced Duplication Detection: More sophisticated algorithm with contextual awareness
- JSX/TSX Support: Full React/Vue component analysis capabilities
- Interactive HTML Reports: Rich visualizations with architectural diagrams
- AI-Powered Insights: Context-aware recommendations using LLM integration
- Framework-Specific Analysis: Specialized patterns for React, Vue, Angular, and Node.js
- Historical Tracking: Code quality trends over time with regression detection
- Multi-Language Support: Python, Java, C# analysis capabilities
- GitHub Actions Integration: Seamless CI/CD workflow templates
- VS Code Extension: Real-time analysis and inline suggestions
- Team Analytics: Aggregate metrics across multiple repositories
- Performance Profiling: Identify performance bottlenecks alongside quality issues
- Test Coverage Integration: Combine quality metrics with coverage data
Contributions welcome! This is a solo side project, so please be patient with reviews.
# Clone and setup
git clone https://github.com/fstepho/insightcode-cli.git
cd insightcode-cli
npm install
# Development
npm run dev # Run with tsx watch
npm test # Run tests
npm run build # Build for production- Keep it simple (KISS principle)
- Maximum 7 npm dependencies
- Performance and accuracy first
- Test critical paths
- Privacy First: Your code never leaves your machine
- Developer Focused: Built by a developer tired of complex tools
- Actionable Metrics: Clear insights that drive improvements
- Fast & Simple: No setup, no config, just results
InsightCode uses evidence-based thresholds:
Built with:
- TypeScript Compiler API - AST parsing
- Commander.js - CLI framework
- Chalk - Terminal styling
- Fast-glob - File discovery
MIT - Use it, fork it, improve it!
Latest: v0.7.1 | Downloads: 