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

npm install -g cyclic-dependency-fixer

Or use locally in your project:

npm install --save-dev cyclic-dependency-fixer

⚡ Quick Start

Basic Usage (No AI)

# Detect circular dependencies
cycfix detect

# Attempt to fix them automatically
cycfix fix --dry-run  # Preview changes
cycfix fix             # Apply fixes

With AI-Powered Analysis

# Set up your API key (one-time)
export ANTHROPIC_API_KEY=sk-ant-xxx  # or OPENAI_API_KEY

# Run with AI-powered recommendations
cycfix fix --ai --generate-code

# Get detailed AI explanations
cycfix fix --ai --explain --generate-code

Deterministic & scalable analysis

# Honor tsconfig paths/references for stable graphs
cycfix detect --tsconfig tsconfig.json

# Use incremental cache (content-hash) for faster CI reruns
cycfix detect --cache --cache-dir .cycfix-cache

# Guardrail safety in huge monorepos
cycfix detect --max-files 5000 --max-depth 40

🤖 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:

   # For Claude (recommended)
   export ANTHROPIC_API_KEY=sk-ant-xxx
   
   # Or for GPT-4
   export OPENAI_API_KEY=sk-xxx

3. Or use CLI flag:

   cycfix fix --ai --ai-key sk-ant-xxx

AI Features

1. Smart Strategy Selection

AI analyzes your code and recommends the best fix strategy:

cycfix fix --ai

Output:

🤖 Analyzing codebase patterns with AI...
   Architecture: Clean Architecture (Layered)
   Patterns found: 3

🤖 Getting AI recommendation for cycle abc123...
   Recommended: extract-shared (85% confidence)
   Reasoning: Both UserService and OrderService depend on shared types.
              Creating a shared types module maintains your layered architecture.

2. Intelligent Code Generation

Get production-ready refactoring code:

cycfix fix --ai --generate-code

Output:

📝 Manual steps to fix:

1. Create shared types module
   File: src/shared/types/user-order.types.ts

   export interface UserId {
     readonly id: string;
   }

   export interface OrderReference {
     readonly userId: UserId;
     readonly orderId: string;
   }

2. Update UserService imports
   File: src/services/user.service.ts
   Line: 3

   - import { OrderReference } from './order.service'
   + import { OrderReference } from '../shared/types/user-order.types'

3. Root Cause Analysis

Understand WHY cycles exist:

cycfix fix --ai --explain

Output:

AI Analysis:

This circular dependency exists because:

1. UserService needs to track user orders (OrderReference type)
2. OrderService needs to validate users (UserId type)
3. Both services define types the other needs

Root Cause: Shared domain types without a common module

Impact:
- Prevents tree-shaking
- Can cause runtime initialization errors
- Makes testing harder (mocking circular deps)

Prevention:
- Create a shared types layer (src/types/)
- Follow the Dependency Inversion Principle
- Use interfaces to define contracts

4. Architecture-Aware Recommendations

AI adapts to YOUR codebase patterns:

✓ Detected: You use dependency injection in 80% of services
✓ Detected: Layered architecture with clear boundaries
✓ Detected: Barrel files (index.ts) for public APIs

Recommendation: Use dependency injection pattern to break this cycle,
as it aligns with your existing architecture.

AI CLI Options

| Option | Description | | -------------------------- | ------------------------------------------------------------- | | --ai | Enable AI-powered analysis | | --ai-provider <provider> | Choose provider: anthropic or openai (default: anthropic) | | --ai-key <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

# 1. Detect with AI analysis
cycfix fix --ai --dry-run

# 2. Review AI recommendations
# AI will show:
# - Detected architecture
# - Recommended strategy with confidence score
# - Reasoning for the recommendation

# 3. Generate refactoring code
cycfix fix --ai --generate-code --dry-run

# 4. Apply fixes
cycfix fix --ai --generate-code

📖 Usage

CLI

Detect Cycles

cycfix detect

Options:

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

Example:

cycfix detect --dir ./src --extensions .ts,.tsx --exclude tests,__mocks__

Fix Cycles

cycfix fix

Options:

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

Example:

cycfix fix --dry-run  # Preview changes
cycfix fix            # Apply fixes with backups

⚙️ Configuration

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

{
  "analysis": {
    "extensions": [".ts", ".tsx"],
    "exclude": ["dist", "coverage"]
  },
  "output": {
    "format": "json",
    "file": "reports/cycfix-report.json"
  },
  "policies": {
    "failOnSeverity": "warn",
    "boundaries": [
      {
        "name": "domain-to-infra",
        "from": "src/domain/**",
        "to": "src/infrastructure/**",
        "severity": "error",
        "description": "Domain layer should not depend on infrastructure"
      }
    ]
  }
}

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:

cycfix detect --format json --output-file reports/cycfix.json
cycfix fix --format sarif --output-file reports/cycfix.sarif

• 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

import { createAnalyzer } from 'cyclic-dependency-fixer';

const analyzer = createAnalyzer('./src');

// Detect cycles
const detection = await analyzer.detect({
  extensions: ['.ts', '.tsx'],
  exclude: ['node_modules', 'dist'],
});

if (!detection.success || !detection.data) {
  throw detection.error;
}

console.log(`Found ${detection.data.cycles.length} cycles`);

// Attempt to fix
const fixAttempt = await analyzer.fix(
  {
    extensions: ['.ts', '.tsx'],
  },
  {
    dryRun: false,
    backup: true,
  },
);

if (!fixAttempt.success || !fixAttempt.data) {
  throw fixAttempt.error;
}

fixAttempt.data.fixResults.forEach((result) => {
  if (result.success) {
    console.log(`✓ Fixed ${result.cycle.id}`);
  } else {
    console.log(`⚠ Manual steps required for ${result.cycle.id}`);
    result.manualSteps?.forEach((step) => {
      console.log(`  - ${step.description}`);
    });
  }
});

Public API Surface

From cyclic-dependency-fixer you can import:

• Core types
  • ModulePath, Module, Cycle, AnalysisResult, FixResult, FixStrategy, FixOptions
• Use cases
  • DetectCyclesUseCase, FixCyclesUseCase
• Infrastructure defaults
  • NodeFileSystem, JavaScriptParser, TarjanCycleDetector
• Fix strategies
  • DynamicImportStrategy, ExtractSharedStrategy
• Factory
  • createAnalyzer(rootDir: string) – returns { detect, fix } helpers as used in the example above

These building blocks let you construct custom pipelines (e.g. your own reporters or policy engines) while reusing the same analysis and fixing logic that powers the CLI.

Tree-Shaking and Subpath Exports

The package is fully tree-shakable with "sideEffects": false and provides granular subpath exports for optimal bundle sizes:

// Import only what you need - rest is tree-shaken away

// Full package (includes everything)
import { createAnalyzer } from '@kitiumai/cyclic-dependency-fixer';

// Domain types only (lightweight, no implementations)
import type { Module, Cycle, AnalysisResult } from '@kitiumai/cyclic-dependency-fixer/domain';

// Specific strategies (tree-shake unused strategies)
import { DynamicImportStrategy } from '@kitiumai/cyclic-dependency-fixer/strategies/dynamic-import';
import { ExtractSharedStrategy } from '@kitiumai/cyclic-dependency-fixer/strategies/extract-shared';

// Specific parsers (tree-shake unused parsers)
import { TypeScriptProjectParser } from '@kitiumai/cyclic-dependency-fixer/parsers/typescript';
import { JavaScriptParser } from '@kitiumai/cyclic-dependency-fixer/parsers/javascript';

// Utilities only
import { extractErrorMetadata } from '@kitiumai/cyclic-dependency-fixer/utils';

// AI features only (tree-shake if not using AI)
import { AIEnhancedFixCyclesUseCase } from '@kitiumai/cyclic-dependency-fixer/ai';

Available Subpath Exports:

| Import Path | Description | Use Case | |-------------|-------------|----------| | @kitiumai/cyclic-dependency-fixer | Full package | Complete functionality | | @kitiumai/cyclic-dependency-fixer/domain | Types and models only | Type-only imports, no runtime code | | @kitiumai/cyclic-dependency-fixer/strategies | All fix strategies | Custom strategy composition | | @kitiumai/cyclic-dependency-fixer/strategies/dynamic-import | Dynamic import strategy | Use only this strategy | | @kitiumai/cyclic-dependency-fixer/strategies/extract-shared | Extract shared strategy | Use only this strategy | | @kitiumai/cyclic-dependency-fixer/parsers | All parsers | Custom parser setup | | @kitiumai/cyclic-dependency-fixer/parsers/javascript | JavaScript parser | JS-only projects | | @kitiumai/cyclic-dependency-fixer/parsers/typescript | TypeScript parser | TS-only projects | | @kitiumai/cyclic-dependency-fixer/utils | Error utilities | Error handling only | | @kitiumai/cyclic-dependency-fixer/ai | AI-powered features | AI analysis without CLI |

Bundle Size Impact:

• Full package: ~150KB (includes all features)
• Types only (/domain): ~2KB (no runtime code)
• Single strategy: ~20KB (vs 50KB for all strategies)
• Single parser: ~30KB (vs 80KB for all parsers)
• Without AI features: ~100KB (saves OpenAI/Anthropic SDK overhead)

Modern bundlers (Webpack 5+, Rollup, Vite, esbuild) automatically tree-shake unused exports when using ES modules.

🎯 Fix Strategies

1. Dynamic Import Strategy

Converts static imports to dynamic imports to break the cycle.

Best for: Simple 2-node cycles where lazy loading is acceptable.

Example:

// Before
import { utils } from './utils';

// After
const { utils } = await import('./utils');

2. Extract Shared Strategy

Creates a new shared module to hold common code.

Best for: Modules in the same directory sharing common functionality.

Example:

Before: a.ts ↔ b.ts
After:  a.ts → shared.ts ← b.ts

📊 Output Example

📊 Analysis Results
──────────────────────────────────────────────────
Total modules analyzed: 45
Analysis duration: 123ms

✗ Found 2 circular dependencies
Affected modules: 4

Cycle #1 (abc12345)
  src/components/Button.tsx →
  src/components/Form.tsx →
  src/components/Button.tsx ⤴

  Import details:
    src/components/Button.tsx:5 imports src/components/Form.tsx
    src/components/Form.tsx:12 imports src/components/Button.tsx

🔧 Fix Results
──────────────────────────────────────────────────

⚠ Could not auto-fix cycle abc12345
  Strategy attempted: dynamic-import

  📝 Manual steps to fix:

  1. Convert static import to dynamic import in src/components/Button.tsx
     File: src/components/Button.tsx
     Line: 5

     // Replace:
     // import x from './Form'

     // With:
     const x = await import('./Form').then(m => m.default || m);

  2. Make the parent function async if needed
     File: src/components/Button.tsx

🏗️ Architecture

Built with Clean Architecture principles:

src/
├── domain/              # Core business logic
│   ├── models/          # Domain entities & types
│   └── interfaces/      # Abstractions (IFileSystem, IParser, etc.)
├── application/         # Use cases
│   ├── DetectCyclesUseCase.ts
│   ├── FixCyclesUseCase.ts
│   └── fix-strategies/  # Fix strategy implementations
├── infrastructure/      # External concerns
│   ├── filesystem/      # File system operations
│   ├── parsers/         # Code parsing
│   └── graph/           # Cycle detection algorithms
└── cli/                 # Command-line interface

Key Design Principles

• ✅ SOLID Principles - Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion
• ✅ Dependency Injection - All dependencies injected for testability
• ✅ Strategy Pattern - Pluggable fix strategies
• ✅ No Any Types - Strict TypeScript typing throughout

🧪 Testing

Comprehensive test coverage (>90%):

npm test              # Run all tests
npm run test:watch    # Watch mode

🔧 Development

# Install dependencies
npm install

# Build
npm run build

# Lint
npm run lint
npm run lint:fix

# Format
npm run format

🧰 API Reference

Programmatic usage with deterministic parsing, caching, and fix orchestration:

import { createAnalyzer, FixStrategy } from 'cyclic-dependency-fixer';

const analyzer = createAnalyzer(process.cwd());

// Detection with tsconfig + cache
const analysis = await analyzer.detect({
  tsconfigPath: 'tsconfig.json',
  enableCache: true,
  cacheDir: '.cycfix-cache',
  maxFiles: 10_000,
});

if (analysis.success && analysis.data.cycles.length > 0) {
  // Attempt targeted fixes
  await analyzer.fix(
    { tsconfigPath: 'tsconfig.json' },
    { strategies: [FixStrategy.EXTRACT_SHARED], dryRun: true },
  );
}

AnalysisResult now surfaces warnings, metrics, and isPartial so CI can gate on degraded runs while still consuming SARIF/JSON output.

📚 Advanced Usage

Custom Fix Strategy

Extend the package with your own fix strategies:

import { IFixStrategy, FixStrategy, Cycle } from 'cyclic-dependency-fixer';

class MyCustomStrategy implements IFixStrategy {
  readonly type = FixStrategy.CUSTOM as any;

  async canFix(cycle: Cycle): Promise<boolean> {
    // Your logic
    return true;
  }

  score(cycle: Cycle): number {
    // Higher score = preferred
    return 100;
  }

  async fix(cycle, modules, fileSystem, dryRun) {
    // Implement your fix
    return {
      /* FixResult */
    };
  }
}

Integration with CI/CD

Add to your GitHub Actions:

- name: Check for circular dependencies
  run: npx cycfix detect

🤝 Contributing

Contributions welcome! Please read our Contributing Guide first.

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

📄 License

MIT © Ashish Yadav

🙏 Acknowledgments

• Inspired by madge for cycle detection
• Uses Tarjan's algorithm for efficient SCC detection
• Built with TypeScript, Commander, Chalk, and Ora

📮 Support

• 🐛 Report a bug
• 💡 Request a feature
• 💬 Discussions
• ⭐ Star on GitHub

Made with ❤️ for the TypeScript community