importfix

importfix

循環インポートは簡単に発生し、目視で解消するのは困難です。コンパイラーが示すのはファイル名であり、ループそのものではありません。importfix はモジュールグラフ（各モジュールのパスと、そのモジュールがインポートするパス）を受け取り、実際にループが発生している箇所を特定します。

循環成分ごとに、代表的なサイクルを正確に 1 つ報告します。巡回順のノードと、開始点に戻るまでのエッジを正確に示します。すべての基本サイクルを列挙するのではなく、各成分につき、正確で再現可能なサイクルを 1 つ報告する仕様です。各サイクルには、推奨される解消箇所も含まれます。これは最初に削除するサイクルエッジで、グラフ全体で依存元が最も少ないものの中から選ばれます。そのため、ループ内で最もインポートされていないモジュールへの影響を最小限に抑えられます。

グラフに含める対象は、次の厳密なルールに従います。

• インポート先が同じ入力内の別のモジュールである場合にのみ、インポートをエッジとして扱います。それ以外のインポートは外部インポートとして統計に計上されますが、エッジにはなりません。
• 重複するインポートは 1 つのエッジにまとめられます。
• モジュールが自分自身をインポートする場合、長さ 1 のサイクルとして、ほかのサイクルと同様に報告されます。
• 代表サイクルは決定的です。成分内で辞書順が最も早いモジュールから開始し、隣接モジュールを辞書順にたどるため、同じグラフからは常に同じ結果が得られます。

純粋なローカル処理です。ネットワーク通信やソースツリーのファイル読み込みは行いません。グラフは呼び出し元から渡されます。

CLI

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

modules.json には modules 配列が含まれます。

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

コマンドはレポートを 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
  }
}

終了コード：成功時は 0、実行時エラー時（読み取れない、または無効な modules ファイルを含む）は 1、使用方法のエラー時は 2 です。

MCP server

npx -y @reneturcios/importfix mcp

MCP クライアントの設定：

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

Tools

• find_import_cycles — モジュールグラフ内の循環インポートを検出し、循環成分ごとに推奨される解消箇所とともに代表的なサイクルを 1 つ報告します。
  • modules（配列、必須、1 件以上）— {path, imports} オブジェクト形式のモジュールです。path はモジュール自身のパス、imports はインポートするパスの一覧です（空の場合もあります）。

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