renameplan

renameplan

重命名文件或导出项很容易开始，却也很容易出错：你能看到导入它的模块，几乎从来都不是全部情况。renameplan 会先让你了解全貌。你提供一个模块图——每个模块的路径、带有任意命名绑定的静态导入、模块导出的名称，以及模块动态导入的路径——再提供你要重命名的文件或导出项。它会返回所有直接引用者、所有间接引用者、编辑它们的安全顺序，以及提醒你谨慎操作的风险标记。它只返回计划；不会读取、重命名或执行任何内容。

对于文件目标，直接引用者是静态导入、动态导入或两者都导入该目标的模块；其 kinds 列表会说明导入类型，静态导入排在前面。间接引用者是通过两条或更多静态边抵达目标的模块，可通过沿反向静态边从目标向外遍历图找到。每个间接引用者都会标明一个 via：即它所导入的、距离目标近一步的模块。如果它有多个符合条件的导入项，via 会选你提供的模块顺序中最先出现的那个，因此对于给定的图，结果是稳定的。动态导入会使模块成为文件的直接引用者，但动态边不会继续传递链路——仅静态导入某个仅通过动态导入引用目标的模块，并不会因此成为间接引用者。

对于导出项目标，只有命名绑定才会计入。若模块导入定义模块时未指定该导出项的名称，或导入的是该模块中的其他名称，则它根本不算引用者，动态导入也不算。间接引用者通过重新导出链路产生：如果某个直接引用者重新导出该名称，那么从该引用者导入此名称的模块就是间接引用者，链路也可以继续经过后续的重新导出模块。对应的规则很严格：如果一个模块本身没有导出该名称，那么即使它从链路中的某个模块导入了该名称，从它导入该名称也不会计入任何引用。

该计划刻意设计得便于直接解读。直接引用者和间接引用者都按路径的代码单元顺序排序。edit_order 会依次列出直接路径、间接路径，最后列出目标模块，这样你就会从外向内编辑，逐步接近要重命名的对象。标记按固定顺序出现：文件被动态引用时为 dynamic_reference，直接引用者重新导出某个导出项时为 reexport_chain，总共影响十个或更多模块时为 wide_blast_radius。

输入格式错误——包括缺少目标、kind 不是 file 或 export、名称或路径为空、模块路径重复、导入项、导出项或动态导入项的类型错误、目标模块不在图中，或定义模块未导出该导出项——都会报错并指出有问题的路径，且不会返回部分计划。未知的额外字段会被忽略，包括项内的字段。

CLI

npx @reneturcios/renameplan plan --input args.json
npx @reneturcios/renameplan --version

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

{
  "target": { "kind": "file", "name": "src/util.ts" },
  "modules": [
    { "path": "src/util.ts", "exports": ["help"] },
    {
      "path": "src/app.ts",
      "imports": [{ "from": "src/util.ts", "names": ["help"] }]
    },
    {
      "path": "src/page.ts",
      "imports": [{ "from": "src/app.ts" }]
    }
  ]
}

结果以 JSON 格式打印：

{
  "target": { "kind": "file", "name": "src/util.ts", "module": null },
  "direct": [{ "path": "src/app.ts", "kinds": ["static"] }],
  "indirect": [{ "path": "src/page.ts", "via": "src/app.ts" }],
  "edit_order": ["src/app.ts", "src/page.ts", "src/util.ts"],
  "flags": [],
  "counts": { "direct": 1, "indirect": 1, "total_affected": 2 }
}

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

MCP 服务

npx -y @reneturcios/renameplan mcp

MCP 客户端配置：

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

工具

• plan_rename — 根据调用方提供的模块图，规划安全的文件或导出项重命名。

  • target（对象，必填）— 要重命名的文件或导出项
    • kind（字符串，必填）— "file" 或 "export"
    • name（字符串，必填，非空）— kind 为 file 时：模块路径；kind 为 export 时：导出项名称
    • module（字符串，架构中可选）— 定义该导出项的模块；kind 为 export 时必填
  • modules（数组，必填，至少 1 项）— 模块图
    • path（字符串，必填，非空）— 模块路径
    • imports（数组，可选）— 静态导入；每项包含 from（字符串，必填，非空）和 names（字符串数组，可选；缺省表示没有具名绑定）
    • exports（字符串数组，可选）— 此模块导出的名称
    • dynamic_imports（字符串数组，可选）— 此模块动态导入的模块路径

  返回 {target, direct, indirect, edit_order, flags, counts}，其中 target 为 {kind, name, module} （kind 为 file 时，module 为 null），direct 是由 {path, kinds} 组成的列表，indirect 是由 {path, via} 组成的列表， counts 为 {direct, indirect, total_affected}。

Docker

docker run -i ghcr.io/cloudcorprecords/renameplan
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/renameplan plan --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