Skip to content

lidge-jun/codexclaw / plugins/codexclaw/skills/dev-architecture

cxc-dev-architecture

Verified

Use for module boundaries and dependencies. Triggers: circular import, coupling, barrel, re-export, validation placement, 모듈 경계, 순환 참조.

references/circular-dependencies.md

View on GitHub
# Circular Dependency Detection & Resolution

Last reviewed: 2026-07-02

Deep reference for detecting, classifying, and resolving circular dependencies across ecosystems.

---

## Detection Commands

### Node.js / TypeScript

```bash
# madge — the standard tool for JS/TS circular detection
npx madge --circular --extensions ts,tsx src/
npx madge --circular --extensions ts,tsx --image graph.svg src/  # visual graph

# dpdm — faster for single-entry analysis
npx dpdm --circular --tree false src/index.ts

# ESLint rule (catches at lint time, not just CI)
# .eslintrc: { "rules": { "import/no-cycle": ["error", { "maxDepth": 3 }] } }

# dependency-cruiser — most configurable
npx depcruise --validate .dependency-cruiser.cjs src/
```

### Python

```bash
# pydeps — package-level cycle detection
pydeps --no-output --show-cycles src/

# importlab — Google's import analysis tool
importlab --trim src/

# Manual: grep for cross-imports
grep -rn "from.*import" src/ | sort | uniq -d
```

### Go

```bash
# Go compiler catches import cycles at build (always enforced)
go build ./...  # cycle = compile error

# For analysis without build:
go vet ./...
```

### Rust

Distinguish Cargo package dependency cycles from references between Rust modules.
Do not claim that compiling proves an acyclic architectural module graph. Use the
repository's dependency rules or inspect module edges when that property matters.

---

## Fix Strategies

### Strategy 1: Interface Extraction

**When:** Two modules need each other's types.

```
BEFORE (circular):
  user.ts imports order.ts (for OrderSummary type)
  order.ts imports user.ts (for UserInfo type)

AFTER (fixed):
  types/contracts.ts defines OrderSummary + UserInfo
  user.ts imports from types/contracts.ts
  order.ts imports from types/contracts.ts
```

### Strategy 2: Dependency Inversion

**When:** Module A calls Module B, but B also needs to notify A.

```
BEFORE (circular):
  payment.ts imports notification.ts (to send receipt)
  notification.ts imports payment.ts (to check payment status)

AFTER (fixed):
  payment.ts defines PaymentObserver interface
  notification.ts implements PaymentObserver
  payment.ts calls observer.onPaymentComplete() — no import of notification
```

### Strategy 3: Event Bus / Mediator

**When:** Multiple modules have cross-cutting communication needs.

```
BEFORE (circular web):
  auth -> user -> billing -> auth (cycle)

AFTER (fixed):
  eventBus.ts (no domain imports)
  auth emits 'user.authenticated'
  user listens 'user.authenticated', emits 'user.profile.loaded'
  billing listens 'user.profile.loaded'
  No module imports another — all communicate via events
```

### Strategy 4: Merge Modules

**When:** Two small modules are truly co-dependent and represent one concept.

```
BEFORE (circular, both small):
  validator.ts (50 lines) <-> parser.ts (40 lines)

AFTER (merged):
  parse-and-validate.ts (90 lines) — single responsibility, no cycle
```

---

## Common Patterns & Resolutions

| Pattern | Root Cause | Resolution |
|---------|-----------|------------|
| Model A references Model B and vice versa | Bidirectional relationship modeled as imports | Extract shared types to `models/types.ts` |
| Service imports Repository that imports Service | Layering violation | Repository never imports Service; use events for reverse flow |
| Test helper imports source, source imports test util | Test infrastructure leaks into production | Move test utils to `__test_utils__/` outside source tree |
| Barrel (index.ts) creates hidden cycle | Re-export graph hides actual dependencies | Remove barrel, use direct imports |
| Monorepo package A depends on B depends on A | Shared types scattered across packages | Create `@org/contracts` package |
| Plugin imports host, host imports plugin | Plugin boundary confused | Define plugin interface in host; plugin implements without importing host internals |

---

## Verification After Fix

After resolving a cycle, always:

1. Re-run detection command — must report zero cycles
2. Run the affected tests/checks at the depth required by `dev` §3; respect explicit execution constraints
3. Check bundle size — extraction should not increase bundle
4. Review the dependency direction — dependencies point inward toward Domain; outer layers depend on inner layers, never the reverse
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 197kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall