Skip to content

README.md

Latest commit

 

History

History
349 lines (253 loc) · 11.4 KB

README.md

File metadata and controls

349 lines (253 loc) · 11.4 KB

🔍 CodePulse CLI

CodePulse Logo

🚀 Advanced Architectural Intelligence & Code Health Engine

Architectural Intelligence • Semantic Modeling • Real-time Monitoring • AI-Agentic Ready

CodePulse is a next-generation architectural health engine designed for large-scale JavaScript, TypeScript, Python, and mixed-language projects. It provides deep, systemic insights into code structure, dependency risks, and evolutionary trends, enabling teams and AI agents to maintain robust and maintainable codebases with surgical precision.

v5.2 Evolution: Featuring our new non-linear scoring model, 🛡️️ Confidence Metric, and Architectural Ghost Mode.

CodePulse Health NPM Version License: MIT Node Version

🌐 Multi-Language Support

English | Українська | Русский | Čeština | 한국어 | Deutsch | Français

📖 Full Documentation

English | Українська | Русский | Čeština | 한국어 | Deutsch | Français

⚡ Quick Start

Installation

npm install -g @archpulse/codepulse

First Scan

# Analyze your project and generate an HTML report
codepulse scan .

# Start the real-time TUI dashboard
codepulse watch .

🚀 Performance & Analysis Engines

CodePulse provides two distinct analysis paths optimized for different workflows. We build a comprehensive systemic model of your entire project, going far beyond standard file-based linting.

Fast Mode (Ultra-fast scanning)

Focus: Instant feedback on core structural health and basic issues.

Tool Engine Runtime (s)
ESLint Baseline ~4.8s
CodePulse Oxlint Engine ~2.8s

Extended Analysis Mode (Full Ecosystem Compatibility)

Focus: Deep architectural insights, complex dependency analysis, and full ESLint rule compatibility.

Tool Engine Runtime (s)
ESLint Raw Baseline ~3.3s
CodePulse ESLint + Systemic Analysis ~5.5s

Why the difference? In Extended Analysis Mode, CodePulse executes your project's full ESLint suite plus its own systemic analysis (dependency graph, circularity detection, architectural boundary checks, and historical churn). The result is a unified report that combines ecosystem-standard linting with deep structural intelligence.

🔍 Scan Modes & Engines

Engine Selection

# Auto-detect (Default)
# Uses ESLint if config is found, otherwise Oxlint
codepulse scan .

# Force ultra-fast mode (Oxlint-powered)
codepulse scan . --engine oxlint

# Force extended analysis mode (higher precision & compatibility)
codepulse scan . --engine eslint
# or
codepulse scan . --precision

Verbose / Debug Modes

# Show program-level issues only
codepulse scan . -d

# Linter debug mode (surfaces raw output from underlying tools)
codepulse scan . -ld

🏆 Core Features & Competitive Advantage

CodePulse is the only tool that seamlessly unifies AST static analysis, Git-based churn & coupling analytics, and native MCP integration for AI-agent workflows. Optimized for modern development environments, it answers 'how it was, how it is, and what to do next'.

Feature Description
🏛️️ Architectural Radar Define layers and catch boundary violations automatically
💡 Semantic Duplication AST-based structural hashing finds identical logic, not just identical lines
🔄 Circular Dependency Breaker Detect and visualize circular imports and dependency loops
⚡ Real-time Watch Mode Interactive TUI dashboard that updates as you code
🚀 Parallel Pipeline Core analysis, fast linters, and security checks run concurrently
📦 Smart Caching Efficiently reuses results from unchanged files
🛠️️ Auto Linter Setup Automatically installs required external linters for your project
🎨 Professional TUI/CLI Rich colors, interactive visualizations, and clear feedback
🌐 7-Language Support Full localization for global development teams
📄 License Management Instantly generate and verify open-source licenses

📋 Command Reference

Primary Commands

Command Description
codepulse scan [dir] Full analysis + HTML report + status badge
codepulse watch [dir] Interactive real-time TUI dashboard
codepulse verify [dir] [GOD TIER] Deep verification: Build, Typecheck, and Tests
codepulse audit [dir] [NEW] Comprehensive architectural audit and AUDIT.md generation
codepulse ghost <file> [NEW] Predict the architectural "blast radius" of changes to a file
codepulse mcp Start the Model Context Protocol (MCP) server for AI agents
codepulse setup-mcp Generate MCP configuration and agent rule files
codepulse stats [dir] Quick project statistics and health overview
codepulse explain [topic] Detailed explanation and remediation advice for specific issues

Advanced Analytics

Command Description
codepulse pr-risk [dir] Evaluate architectural risk of Pull Request changes
codepulse coupling [dir] Detect "Temporal Coupling" (files that change together)
codepulse health-trend Visualize health score evolution over time
codepulse heatmap [dir] Interactive TUI treemap of codebase risk zones
codepulse diff <branch> Compare architectural health between branches
codepulse time-machine Analyze dependency graph history and evolution
codepulse profile Correlate runtime profiler data with code complexity
codepulse synth [dir] Generate a synthetic stress test plan for your architecture

🏛️️ Architecture Governance

Enforce your project's structure and boundaries using .codepulse.json:

{
  "architecture": {
    "layers": [
      { 
        "name": "UI", 
        "pattern": "src/ui/.*", 
        "allowDependenciesFrom": ["Services", "Utils"] 
      },
      { 
        "name": "Services", 
        "pattern": "src/services/.*", 
        "allowDependenciesFrom": ["DB", "Utils"] 
      },
      { 
        "name": "DB", 
        "pattern": "src/db/.*", 
        "allowDependenciesFrom": ["Utils"] 
      }
    ],
    "strict": true
  }
}

🔌 Plugin System

Extend CodePulse with custom analysis rules tailored to your team's needs.

Creating a Plugin

Create a TypeScript/JavaScript plugin in your project's plugins/ directory:

import { Rule, AnalysisContext, Issue } from '@archpulse/codepulse';

export default class CustomQualityRule implements Rule {
  name = 'custom-quality-rule';
  description = 'Ensures team-specific standards are met';
  version = '1.0.0';
  category = 'code-quality';

  run(context: AnalysisContext): Issue[] {
    // Custom analysis logic
    return [];
  }
}

📘 Explore Plugin Development →

🤖 AI-Agent Integration (MCP)

CodePulse features a native Model Context Protocol (MCP) server, enabling AI assistants (Claude, Cursor, etc.) to perform expert-level architectural analysis.

Setup for AI Assistants

# Configure MCP and generate IDE-specific rules
codepulse setup-mcp

This command generates optimized rules for various IDEs and agents (.cursorrules, .clinerules, CLAUDE.md, etc.), instructing them to use CodePulse tools for deeper context.

Agent-Specific Tools (17+ Tools)

Tool Description
codepulse_identity Get project health score and identify critical "God Files"
get_file_context Deep architectural dossier (coupling, risk, complexity) for a file
predict_change_impact Predict the transitive blast radius of a symbol change
optimize_context [NEW] Filter and identify minimal relevant files for a specific goal
find_similar_functions AST-based structural duplication search across the project
suggest_split_strategy Concrete decomposition and refactoring plan for large files
simulate_edit Validate proposed code changes against architectural rules

🛠️️ CI/CD Integration

Automate architectural reviews in your GitHub workflows.

- name: CodePulse Review
  uses: archpulse/codepulse@v5
  with:
    command: 'review'
    github_token: ${{ secrets.GITHUB_TOKEN }}

CI Capabilities:

  • Review: Post PR summaries and impact analysis directly to GitHub.
  • Verify: Enforce build, typecheck, and test pass rates.
  • Audit: Generate AUDIT.md artifacts for every build.

🚀 Visualizations

HTML Report
Interactive HTML Report 		Temporal Coupling
Temporal Coupling Analytics 		Ghost Mode
Architectural Ghost Mode
Health Trend
Health Score Evolution 		Risk Heatmap
Interactive Risk Heatmap 		Real-time TUI
Advanced TUI Dashboard

🌐 Localization

Full support for multiple languages:

# View help in French
codepulse --help --lang fr

# Scan in Ukrainian
codepulse scan . --lang ua

# Watch in German
codepulse watch . --lang de

Supported: English, Українська, Русский, Čeština, 한국어, Deutsch, Français

💻 System Requirements

  • Node.js: 16.0.0+
  • OS: Linux, macOS, Windows
  • RAM: 512MB (1GB+ recommended for large projects)

🤝 Contributing

We welcome contributions! Please see our Contributing Guide to get started.

git clone https://github.com/archpulse/codepulse-cli.git
npm install
npm test
npm run dev -- scan .

📄 License

MIT License © 2024 ArchPulse

⭐ Love CodePulse? Give us a star on GitHub!

archpulse