renameplan

Renaming a file or an export is easy to start and easy to get wrong: the module you can see importing it is rarely the whole story. renameplan makes you look at the whole story first. You supply a module graph — each module's path, its static imports with any named bindings, the names it exports, and the paths it imports dynamically — plus the file or export you want to rename, and it returns every direct referencer, every indirect referencer, a safe order to edit them in, and the risk flags that should slow you down. It returns the plan only; nothing is read, renamed, or executed.

For a file target, a direct referencer is a module that imports the target statically, dynamically, or both; its kinds list says which, static first. Indirect referencers are modules that reach the target through two or more static edges, found by walking the graph outward from the target over reverse static edges. Each indirect referencer names a via: the module it imports that sits one step closer to the target. When several of its imports qualify, the via is the one that appears first in the order you supplied the modules, so the answer is stable for a given graph. A dynamic import makes a module a direct referencer of a file, but dynamic edges do not carry a chain further — a module that statically imports a dynamic-only referencer is not, by that path alone, an indirect referencer.

For an export target, only named bindings count. A module that imports the defining module without naming the export, or that imports a different name from it, is not a referencer at all, and neither is a dynamic import. Indirect referencers arrive through re-export chains: if a direct referencer re-exports the name, a module that imports the name from that referencer is an indirect referencer, and the chain can continue through further re-exporters. The mirror rule is strict: importing the name from a module that does not itself export it counts nowhere, even if that module imports the name from somewhere in the chain.

The plan is deliberately mechanical to read. Direct and indirect referencers are each sorted by path in code-unit order. edit_order lists the direct paths, then the indirect paths, then the target module last, so you work inward toward the thing being renamed. Flags arrive in a fixed order: dynamic_reference when a file is referenced dynamically, reexport_chain when an export is re-exported by a direct referencer, and wide_blast_radius when ten or more modules are affected in total.

Malformed input — a missing target, a kind other than file or export, an empty name or path, a duplicate module path, a badly typed import, export, or dynamic import entry, a target module that is not in the graph, or an export the defining module does not export — is an error naming the offending path, with no partial plan. Unknown extra fields are ignored, including inside items.

CLI

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

args.json contains the full arguments object:

{
  "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" }]
    }
  ]
}

The result is printed as 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 }
}

Exit codes: 0 on success, 1 on a runtime error (including an unreadable or invalid input file, or invalid input), 2 on a usage error.

Related MCP server: ropey

MCP server

npx -y @reneturcios/renameplan mcp

MCP client config:

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

Tools

• plan_rename — Plan a safe file or export rename from a caller-supplied module graph.

  • target (object, required) — the file or export to rename

    • kind (string, required) — "file" or "export"

    • name (string, required, non-empty) — for kind file: the module path; for kind export: the export name

    • module (string, optional in the schema) — module defining the export; required for kind export

  • modules (array, required, at least 1 item) — the module graph

    • path (string, required, non-empty) — module path

    • imports (array, optional) — static imports; each item has from (string, required, non-empty) and names (array of strings, optional; absent means no named bindings)

    • exports (array of strings, optional) — names this module exports

    • dynamic_imports (array of strings, optional) — module paths this module imports dynamically

  Returns {target, direct, indirect, edit_order, flags, counts}, where target is {kind, name, module} (module is null for kind file), direct is a list of {path, kinds}, indirect is a list of {path, via}, and counts is {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

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