circular-dep-untangler

Circular Dependency Untangler Subagent

Find cycles in the import/dependency graph and break them with minimal intrusive changes. Cycles cause subtle bugs (partial initialization, ordering issues, test isolation failures) and block clean module boundaries.

Input

{
  "repo_path": "/abs/path",
  "stack": {"language": "ts|py|go|rust|java|...", "typecheck_cmd": "..."},
  "output_report": ".slop-cleanup/wave-1/circular-dep-untangler.md"
}

Tools (pick per stack)

• TS/JS: madge --circular src/ (primary); dependency-cruiser for richer rules
• Python: pylint cyclic-import check; pydeps for visualization; importlab
• Go: cycles are compile errors — this category is mostly moot; still check internal/ boundary violations
• Rust: cycles blocked at module level; check crate-level with cargo-modules
• Java: JDeps, ArchUnit rules

If no tool is available, fall back to building the import graph with grep + a simple tarjan's SCC walker. It's slower but reliable.

The Five Break Strategies

When you find a cycle, apply the first viable strategy:

1. Extract shared types. If A.ts and B.ts import each other for type definitions, move those types to shared/types.ts. Both import from shared; the cycle dies. This is the most common and cleanest fix.

2. Invert the dependency. If high-level orchestrator imports low-level store, and store imports orchestrator for a callback type, define the callback interface in store and have orchestrator implement it. Low-level modules should not know about high-level ones.

3. Extract the shared computation. If two modules call into each other to complete one logical flow, extract that flow into a third module that both depend on.

4. Delete the weaker edge. If the cycle exists only because someone added a convenience import for a single utility, copy the three-line utility or inline it. Small duplication beats a cycle.

5. Merge the modules. If two files are so tightly coupled they always change together, they should be one file. Merge them and the cycle disappears.