depmap

depmap

大型单体仓库很容易让人摸不清头绪：集合中的哪些软件包实际依赖哪些其他软件包，哪些位于顶层且没有任何依赖，哪些位于底层且不依赖任何内部软件包，以及内部图是否形成了循环。depmap 获取软件包图——每个软件包的名称及其依赖项名称——并绘制出完整的映射：

• 每个软件包的条目——对于每个软件包，列出其内部依赖项（depends_on）、依赖它的软件包（depended_by），以及 external_count：其依赖项名称中有多少指向集合之外。外部名称只计数，不绘制，也不会导致错误——软件包可以自由依赖大型单体仓库中不存在的库。
• 边、根和叶——每个内部依赖项都表示为一个 {from, to} 边；列出根（没有任何内部软件包依赖的包）和叶（没有内部依赖项的包）。
• 两种方式呈现循环——cyclic_packages 列出位于任意循环中的所有软件包：属于包含多个软件包的强连通分量的成员，以及任何依赖自身的软件包。此外，cycle 会报告一个具体的循环，该循环由深度优先搜索找到，搜索按升序访问名称和依赖项。发现循环不代表错误。
• Mermaid 图——将映射呈现为 graph TD 图表，可粘贴到任意 Mermaid 渲染器中。不是有效 Mermaid ID 的软件包名称会获得经过清理的 ID（@scope/app 会变成 _scope_app），并通过声明行将该 ID 与真实名称关联起来。

映射之前，会对单个软件包的 dependencies 中重复的条目去重；结果中的所有列表都会按升序排列，因此相同的图始终会生成完全相同的映射。格式错误的输入——缺少软件包列表或列表为空、缺少或重复的软件包名称、字段类型错误——会导致验证错误，并指出出错路径（例如 packages[1].dependencies[0] must be a string），且不会生成部分映射。计算是纯本地操作：不访问网络、不需要配置，也不会读取你传入的输入以外的文件。

命令行

npx @reneturcios/depmap map --input args.json
npx @reneturcios/depmap --version

args.json 包含完整的参数对象：

{
  "packages": [
    { "name": "core" },
    { "name": "lib", "dependencies": ["core"] },
    { "name": "app", "dependencies": ["lib", "react"] }
  ]
}

每个软件包的 dependencies 默认为 []；此处 react 不属于该集合，因此只会出现在 app 的 external_count 中。映射会以 JSON 格式打印：

{
  "packages": [
    { "name": "app", "depends_on": ["lib"], "depended_by": [], "external_count": 1 },
    { "name": "core", "depends_on": [], "depended_by": ["lib"], "external_count": 0 },
    { "name": "lib", "depends_on": ["core"], "depended_by": ["app"], "external_count": 0 }
  ],
  "edges": [
    { "from": "app", "to": "lib" },
    { "from": "lib", "to": "core" }
  ],
  "roots": ["app"],
  "leaves": ["core"],
  "has_cycle": false,
  "cycle": [],
  "cyclic_packages": [],
  "mermaid": "graph TD\n  app --> lib\n  lib --> core"
}

退出代码：成功时为 0，运行时错误时为 1（包括输入文件无法读取或无效，以及输入无效），用法错误时为 2。

MCP 服务

npx -y @reneturcios/depmap mcp

MCP 客户端配置：

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

工具

• map_internal_dependencies — 映射大型单体仓库的内部依赖项。
  • packages（数组，必填，至少一个）——软件包对象数组，格式为 {name, dependencies?}；name 在集合中必须唯一，每个 dependencies 条目要么指向另一个已提供的软件包（内部），要么是其他任何内容（外部，只计数）

返回 {packages, edges, roots, leaves, has_cycle, cycle, cyclic_packages, mermaid}。

Docker

docker run -i ghcr.io/cloudcorprecords/depmap
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/depmap map --input /w/args.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 — 版权所有 (c) 2026 Rene Turcios