Importfix

importfix

Circular imports are easy to create and miserable to unwind by eye: the compiler names a file, not the loop. importfix takes a module graph — each module's path and the paths it imports — and works out where the loops actually are.

For every cyclic component it reports exactly one representative cycle: the exact nodes in traversal order and the edges between them, closing back to the start. It does not enumerate every elementary cycle; one exact, reproducible cycle per component is the contract. Each cycle also carries a suggested break point — the cycle edge to remove first, chosen because its target has the fewest dependents in the whole graph, so breaking it disturbs the least-imported module on the loop.

The graph rules are strict about what counts:

• An import only becomes an edge when it names another module in the same input. Imports of anything else are external: counted in the stats, never edged.
• Duplicate imports collapse into one edge.
• A module importing itself is a cycle of one, reported like any other.
• The representative cycle is deterministic: it starts at the component's lexicographically smallest module and follows neighbours in lexicographic order, so the same graph always yields the same answer.

Pure local computation: no network, no filesystem reads of your source tree — the graph is supplied by the caller.

CLI

npx @reneturcios/importfix cycles --modules modules.json

npx @reneturcios/importfix --version

modules.json contains the modules array:

[

{"path": "src/a.ts", "imports": ["src/b.ts"]}, {"path": "src/b.ts", "imports": ["src/a.ts", "node:fs"]} ]

The command prints the report as JSON:

{

"has_cycles": true, "cycles": [ { "nodes": ["src/a.ts", "src/b.ts"], "edges": [ {"from": "src/a.ts", "to": "src/b.ts"}, {"from": "src/b.ts", "to": "src/a.ts"} ], "suggested_break": { "from": "src/a.ts", "to": "src/b.ts", "reason": "target has the fewest dependents in the graph (1)" } } ], "stats": { "module_count": 2, "edge_count": 2, "external_imports": 1, "cyclic_module_count": 2 } }

Exit codes: 0 on success, 1 on a runtime error (including an unreadable or invalid modules file), 2 on a usage error.

MCP server

npx -y @reneturcios/importfix mcp

MCP client config:

{

"mcpServers": { "importfix": { "command": "npx", "args": ["-y", "@reneturcios/importfix", "mcp"] } } }

Tools

• find_import_cycles — Detect circular imports in a module graph and report one representative cycle per cyclic component, with a suggested break point.
• modules (array, required, at least one item) — modules as {path, imports} objects; path is the module's own path and imports lists the paths it imports (may be empty)

Docker

docker run -i ghcr.io/cloudcorprecords/importfix

docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/importfix cycles --modules /w/modules.json

Development

npm install

npm run build # tsc -> dist/ npm test # tsx --test test/*.test.ts (pure local, no network) npm run dev # run the CLI from source

License

MIT — Copyright (c) 2026 Rene Turcios