@kitiumai/cyclic-dependency-fixer weekly downloads statistics

cyclic-dependency-fixer

🔄 Detect and automatically fix cyclic dependencies in JavaScript/TypeScript projects with AI-powered analysis

cyclic-dependency-fixer is a lightweight, powerful tool that not only detects circular dependencies but also provides intelligent auto-fix strategies powered by AI (Claude, GPT-4). Get context-aware recommendations, automated refactoring code, and actionable insights.

Table of Contents

• Features • Installation • Quick Start • AI-Powered Features • Usage • Fix Strategies • Output Example • Architecture • Testing • Development • Advanced Usage • Contributing • License • Support

✨ Features

Core Features

• 🔍 Fast Detection - Uses Tarjan's algorithm for efficient cycle detection (O(V + E)) • 🛠️ Auto-Fix Strategies - Attempts to automatically fix cycles when safe • 📝 Manual Fix Guidance - Provides clear, actionable steps when auto-fix isn't possible • 🎯 Multiple Strategies - Dynamic imports, shared module extraction, and more • 📊 Clear Output - User-friendly CLI with colored output • 🔌 Extensible - Clean architecture allows custom fix strategies • 💪 Type-Safe - Written in TypeScript with strict typing • 🪶 Lightweight - Minimal dependencies, uses regex-based parsing • 📄 Enterprise Reports - Export JSON or SARIF for CI/CD and audits • 🛡️ Policy Guardrails - Enforce architectural boundaries before merging • 🧭 Deterministic Graphs - TypeScript project-aware parsing with tsconfig support and path resolution • 💾 Incremental Cache - Opt-in content-hash cache for stable CI timings and repeated runs • 🛟 Degraded-but-useful Results - Partial outputs with warning surfacing when some files fail to parse • 📈 Operational Insights - Metrics in CLI output (parser used, cache hits) for observability

🤖 AI-Powered Features (NEW!)

• Smart Strategy Selection - AI analyzes your code and recommends the best fix strategy • Codebase Pattern Learning - Understands your architecture and coding patterns • Intelligent Refactoring - Generates production-ready refactoring code • Root Cause Analysis - Explains WHY circular dependencies exist • Context-Aware Suggestions - Recommendations tailored to your codebase • Multiple AI Providers - Support for Claude (Anthropic) and GPT-4 (OpenAI)

🚀 Installation

Or use locally in your project:

⚡ Quick Start

Basic Usage (No AI)

With AI-Powered Analysis

Deterministic & scalable analysis

🤖 AI-Powered Features

Why Use AI?

Traditional static analysis can detect cycles but struggles with context. AI understands:

• Semantic relationships between modules • Your codebase's architecture (layered, hexagonal, clean architecture, etc.) • Common patterns you use (dependency injection, factory pattern, etc.) • Why cycles exist (shared types, bidirectional relationships, etc.)

Setup

1. Get an API Key (choose one): • Claude (Anthropic): https://console.anthropic.com/ • GPT-4 (OpenAI): https://platform.openai.com/api-keys

2. Set Environment Variable:

3. Or use CLI flag:

AI Features

1. Smart Strategy Selection

AI analyzes your code and recommends the best fix strategy:

Output:

2. Intelligent Code Generation

Get production-ready refactoring code:

Output:

3. Root Cause Analysis

Understand WHY cycles exist:

Output:

4. Architecture-Aware Recommendations

AI adapts to YOUR codebase patterns:

AI CLI Options

| Option | Description |

| --ai | Enable AI-powered analysis | | --ai-provider | Choose provider: anthropic or openai (default: anthropic) | | --ai-key | Provide API key directly (or use env var) | | --explain | Generate AI explanations of why cycles exist | | --generate-code | Generate complete refactoring code with AI |

Example Workflow

📖 Usage

CLI

Detect Cycles

Options:

• -d, --dir - Root directory to analyze (default: current directory) • -e, --extensions - File extensions to include (default: .js,.jsx,.ts,.tsx) • -x, --exclude - Patterns to exclude (comma-separated) • --include-node-modules - Include node_modules in analysis • --max-depth - Maximum depth for cycle detection (default: 50) • --config - Load shared defaults from cycfix.config.json • --format - Choose human or machine readable output • --output-file - Write the report to disk instead of stdout

Example:

Fix Cycles

Options:

• -d, --dir - Root directory to analyze • -e, --extensions - File extensions to include • -x, --exclude - Patterns to exclude • --dry-run - Preview fixes without modifying files • --no-backup - Don't create backup files • --auto - Automatically apply fixes without confirmation • --config - Load shared defaults from cycfix.config.json • --format - Emit CLI-friendly output or JSON/SARIF for CI • --output-file - Persist the report

Example:

⚙️ Configuration

Share defaults with your team by checking in a cycfix.config.json at the repo root:

CLI flags always win, so you can override config values per run (cycfix detect --format sarif --output-file .reports/cycfix.sarif).

🛡️ Policy Enforcement

Large codebases often need to enforce architectural boundaries (e.g., domain cannot import infrastructure). Define rules under policies.boundaries and cyclic-dependency-fixer will:

• Match edges using glob-style wildcards (*, **) • Annotate reports with the offending imports • Fail the command automatically when a violation of the configured severity is detected

You can optionally provide recommendedStrategies for each rule to guide reviewers toward the right remediation path.

📤 Enterprise Reporting

Need to feed results into GitHub Advanced Security, Azure DevOps, or custom dashboards? Use the structured reporters:

• JSON: optimized for custom ingestion pipelines • SARIF: drop directly into GitHub code scanning or Azure DevOps to annotate PRs

🧩 Programmatic API

The package exposes a small, focused API for embedding cyclic-dependency-fixer into your own tooling.

Quick Start Example

Public API Surface

From cyclic-dependency-fixer you can import:…

Description from the npm listing.