deadpath

deadpath

代码库中会不断积累无人使用的导出：为某个后来被删除的调用方编写的辅助函数、为了“以防万一”而保留的常量，或某个曾有其他代码导入其名称、因而仍随项目发布的整个模块。deadpath 根据证据给出答案。你向它提供一组模块——每个模块的路径、导出的名称以及进行的导入——它就会找出这组模块中从未在任何地方被导入的导出名称：

• 各模块摘要 — 对每个模块，列出其未使用的导出名称、导出总数（去重后），以及已使用的导出数量。
• 未使用导出的列表 — 列出每个未使用的导出，形式为 {module, name}，并排序，方便直接生成清理列表或 CI 检查。
• 整组统计 — 导出总数、未使用导出的总数，以及 dead_ratio：这组模块中已导出但未使用的部分所占比例，四舍五入到小数点后四位。

判定规则很简单：只要这组模块中有某个模块从该导出所属模块导入了该名称，就算该导出已使用——模块从自身导入自己的名称也算，和其他导入一样。入口模块是唯一例外：将模块标记为 entry: true，其所有导出都会算作已使用，因为入口点的导出属于公共接口，会被这组模块之外的代码使用。names 列表为空的导入属于副作用导入：它会运行目标模块，但不会使用其中任何具名导出，因此不会让任何导出继续保留。

导入范围是封闭的：每个导入的 from 都必须指定所提供的模块之一。这样，未使用的判定才有意义——图的完整性由构造方式保证；若导入指向这组模块之外，则会产生指出问题路径的校验错误（例如 modules[0].imports[1].from must name a supplied module），而不会在证明中留下未说明的缺口。任何格式错误的输入——包括重复的模块路径、无效的 exports 条目或非布尔值的 entry——都会以同样的方式报错并指出问题路径，且不会生成部分报告。计算是纯本地的：不访问网络、不需要配置，也不会读取你传入的输入之外的文件。

CLI

npx @reneturcios/deadpath find --input args.json
npx @reneturcios/deadpath --version

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

{
  "modules": [
    { "path": "src/main.ts", "exports": ["boot"], "entry": true },
    {
      "path": "src/util.ts",
      "exports": ["fmt", "parse", "legacy"],
      "imports": []
    },
    {
      "path": "src/app.ts",
      "imports": [{ "from": "src/util.ts", "names": ["fmt", "parse"] }]
    }
  ]
}

每个模块的 exports 和 imports 默认值均为 []，每个导入的 names 默认值为 []，而 entry 默认值为 false。在此示例中，src/util.ts 导出了 legacy，但没有任何模块导入它，因此报告如下：

{
  "modules": [
    { "path": "src/app.ts", "dead_exports": [], "used_count": 0, "export_count": 0 },
    { "path": "src/main.ts", "dead_exports": [], "used_count": 1, "export_count": 1 },
    { "path": "src/util.ts", "dead_exports": ["legacy"], "used_count": 2, "export_count": 3 }
  ],
  "dead_exports": [
    { "module": "src/util.ts", "name": "legacy" }
  ],
  "total_exports": 4,
  "total_dead": 1,
  "dead_ratio": 0.25
}

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

MCP 服务

npx -y @reneturcios/deadpath mcp

MCP 客户端配置：

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

工具

• find_dead_exports — 查找没有任何模块导入的导出名称。

  • modules（数组，必填，至少一个元素）——模块列表，每个模块为 {path, exports?, imports?, entry?} 对象；path 在整组中必须唯一；每个导入为 {from, names?} 对象，其中 from 指定所提供的模块之一；entry: true 表示该模块的所有导出都算作已使用

  返回 {modules, dead_exports, total_exports, total_dead, dead_ratio}。

Docker

docker run -i ghcr.io/cloudcorprecords/deadpath
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/deadpath find --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 — Copyright (c) 2026 Rene Turcios