# 🔍 CodePulse CLI

### 🚀 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](./badge.svg) [![NPM Version](https://img.shields.io/npm/v/@archpulse/codepulse?style=for-the-badge&color=0ea5e9)](https://www.npmjs.com/package/@archpulse/codepulse) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT) [![Node Version](https://img.shields.io/badge/Node-16%2B-brightgreen?style=for-the-badge)](https://nodejs.org/) --- ### 🌐 Multi-Language Support [English](./README.md) | [Українська](./translations/README.ua.md) | [Русский](./translations/README.ru.md) | [Čeština](./translations/README.cs.md) | [한국어](./translations/README.ko.md) | [Deutsch](./translations/README.de.md) | [Français](./translations/README.fr.md) ### 📖 Full Documentation [English](./docs/CODEPULSE_FULL_DOCS.md) | [Українська](./translations/CODEPULSE_FULL_DOCS.ua.md) | [Русский](./translations/CODEPULSE_FULL_DOCS.ru.md) | [Čeština](./translations/CODEPULSE_FULL_DOCS.cs.md) | [한국어](./translations/CODEPULSE_FULL_DOCS.ko.md) | [Deutsch](./translations/CODEPULSE_FULL_DOCS.de.md) | [Français](./translations/CODEPULSE_FULL_DOCS.fr.md)

--- ## ⚡ Quick Start ### Installation ```bash npm install -g @archpulse/codepulse ``` ### First Scan ```bash # 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 ```bash # 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 ```bash # 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 ` | **[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 ` | 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`: ```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: ```typescript 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 →](./docs/PLUGINS.md)** --- ## 🤖 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 ```bash # 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. ```yaml - 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

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

--- ## 🌐 Localization Full support for multiple languages: ```bash # 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](./CONTRIBUTING.md) to get started. ```bash 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**