importfix

importfix

循环导入很容易产生，靠肉眼排查却十分痛苦：编译器指出的是文件，而不是循环。importfix 接收一个模块图——包含每个模块的路径及其导入的路径——并找出循环实际出现的位置。

对于每个循环分量，它都会报告一个且仅一个代表性循环：按遍历顺序排列的确切节点，以及节点间的边，最后回到起点。它不会枚举所有基本循环；每个分量报告一个确切且可复现的循环，这是它的约定。每个循环还会附带一个建议的断开点——优先移除的循环边。该边的目标模块在整个图中依赖者最少，因此移除它对循环中被导入最少的模块影响最小。

图的规则对统计范围有严格要求：

• 只有当导入项指向同一输入中的另一个模块时，才会形成边。其他导入都属于外部导入：计入统计数据，但不会形成边。
• 重复导入会合并为一条边。
• 模块导入自身时，形成一个长度为 1 的循环，处理方式与其他循环相同。
• 代表性循环具有确定性：从分量中字典序最小的模块开始，并按字典序遍历相邻节点，因此相同的图始终会得到相同结果。

纯本地计算：不会访问网络，也不会读取源代码树中的文件——调用方会提供图。

命令行

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 服务

npx -y @reneturcios/importfix mcp

MCP 客户端配置：

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

工具

• find_import_cycles — 检测模块图中的循环导入，并为每个循环分量报告一个代表性循环及建议的断开点。
  • modules（数组，必填，至少包含一项）——由 {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

开发

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

许可证

MIT — Copyright (c) 2026 Rene Turcios