Circular Dependency Detector

In 2026, a team ships a refactor, every test passes, and three weeks later production throws "cannot access X before initialization" — from a file nobody touched. The cause is a circular import that had worked purely by the accident of module load order, until a single new import shifted that order. Circular dependencies are the bug class that hides: invisible in review, silent in most test runs, and detonating far from where they live. This tool exists to make them visible on demand, before they ship.

A circular dependency is simply a cycle in the directed graph of "module A imports module B." The formal name for a tangled region is a strongly connected component — a set of modules where every one can reach every other by following imports — and the canonical way to find them is Tarjan's algorithm, published by Robert Tarjan in 1972, which discovers all SCCs in a single linear-time depth-first traversal. It's the same algorithm running in your browser when you click Detect, and it's why the analysis stays instant even on graphs of thousands of modules.

Different languages punish cycles differently, and the variety is instructive. Go took the hardest line: an import cycle is a compile error, full stop, so Go programmers learn to invert dependencies by reflex. Python is the most treacherous — a cycle often imports fine until the order changes, then raises "ImportError: cannot import name … (most likely due to a circular import)". JavaScript and TypeScript hoist and partially-evaluate modules, so a cyclic import can yield undefined at the top level while working inside a function; barrel files (index.ts re-exports) are a notorious source. Java and C# compile cycles happily but then surprise you at runtime through static-initializer order or, in Spring, a BeanCurrentlyInCreationException.

Beyond the crashes, cycles quietly tax everything around them. A bundler can't tree-shake or cleanly code-split modules that depend on each other, so a cycle can drag unrelated code into the same chunk and inflate the bundle the user downloads — which is why the bundle analyzer and this tool answer two halves of the same architecture question. Cyclic modules also can't be unit-tested in isolation, because you can't load one without the other, so mocks break down and tests silently become integration tests. And refactoring an SCC is dangerous precisely because it has no safe edit order — there's no module you can change first.

The fix is almost always dependency inversion: find what the two coupled modules actually share, extract it into a third module that both import, and the arrows now point one way. Where the coupling is only about wiring, dependency injection or a lazy import breaks the cycle; where it's only about types, TypeScript's import typeis erased at runtime and removes the cycle for free. The hard part was never the fix — it was knowing which edge to cut, which is exactly what this tool computes: for each cycle it names the highest-leverage import to remove, and for the whole graph it builds a minimal cut-set, because one well-chosen cut often breaks many overlapping circuits at once.

The discipline that keeps a codebase acyclic is the same one that keeps it secure and lean: measure continuously and fail loudly. Run an acyclicity check in CI (madge --circular, dependency-cruiser, or eslint-plugin-import/no-cycle) so a new cycle can never merge unnoticed, and treat the acyclicity score the way you treat test coverage — a number that should only go up. This analyzer is the fast feedback loop for that discipline, and it pairs with the npm dependency analyzer and the vulnerability scanner to keep the whole dependency story — structure, weight, and safety — under control.