renameplan

renameplan

ファイルやエクスポートの名前変更は簡単に始められますが、間違えやすい作業です。インポートしていることが目に見えるモジュールだけで、全体像がわかることはほとんどありません。renameplan では、まず全体像を確認します。モジュールグラフ（各モジュールのパス、名前付きバインディングを含む静的インポート、エクスポートする名前、動的にインポートするパス）と、名前を変更するファイルまたはエクスポートを指定すると、すべての直接参照元、間接参照元、編集する安全な順序、作業を慎重に進めるべきリスクフラグが返されます。返されるのは計画だけです。読み取り、名前変更、実行は一切行われません。

ファイルを対象とする場合、直接参照元とは、対象を静的、動的、またはその両方でインポートするモジュールです。そのkindsリストには、該当する種類が静的を先にして示されます。間接参照元とは、対象から逆方向の静的エッジをたどってグラフを外側へ探索したとき、2つ以上の静的エッジを経由して対象に到達するモジュールです。各間接参照元にはviaが示されます。これは、そのモジュールがインポートするモジュールのうち、対象に1段階近いものです。該当するインポートが複数ある場合、viaには、指定したモジュールの順序で最初に現れるものが選ばれます。そのため、同じグラフであれば結果は常に一定です。動的インポートがあると、そのモジュールはファイルの直接参照元になりますが、動的エッジを介して参照チェーンが続くことはありません。動的インポートのみを持つ参照元を静的にインポートするモジュールは、その経路だけでは間接参照元になりません。

エクスポートを対象とする場合、名前付きバインディングのみが対象です。定義元のモジュールをインポートしていても、対象のエクスポート名を指定していないモジュールや、別の名前をインポートしているモジュールは、参照元ではありません。動的インポートも参照元にはなりません。間接参照元は再エクスポートのチェーンをたどって見つかります。直接参照元がその名前を再エクスポートしている場合、その直接参照元から名前をインポートするモジュールは間接参照元となり、さらに再エクスポートするモジュールを経由してチェーンが続くこともあります。逆の場合のルールも厳密です。チェーン内のどこかから名前をインポートしていても、そのモジュール自体がその名前をエクスポートしていなければ、どこにもカウントされません。

この計画は、機械的に読み取れるよう意図的に構成されています。直接参照元と間接参照元は、それぞれコード単位順でパス順に並べ替えられます。edit_orderには、直接参照元のパス、次に間接参照元のパス、最後に対象モジュールの順で並ぶため、名前を変更する対象に向かって内側へ作業を進められます。フラグは固定の順序で並びます。ファイルが動的に参照されている場合はdynamic_reference、直接参照元がエクスポートを再エクスポートしている場合はreexport_chain、影響を受けるモジュールが合計10個以上の場合はwide_blast_radiusです。

不正な入力（対象の欠落、fileまたはexport以外のkind、空の名前またはパス、モジュールパスの重複、型が不正なインポート、エクスポート、動的インポートのエントリー、グラフに存在しない対象モジュール、または定義元モジュールがエクスポートしていないエクスポート）は、該当するパスを示すエラーとなり、計画は部分的にも返されません。項目内も含め、未知の追加フィールドは無視されます。

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（object、必須）— 名前を変更するファイルまたはエクスポート
    • kind（string、必須）— "file" または "export"
    • name（string、必須、空でないこと）— kind が file の場合はモジュールパス、kind が export の場合はエクスポート名
    • module（string、スキーマ上は任意）— エクスポートを定義するモジュール。kind が export の場合は必須です
  • modules（array、必須、1 件以上）— モジュールグラフ
    • path（string、必須、空でないこと）— モジュールパス
    • imports（array、任意）— 静的インポート。各項目には from（string、必須、空でないこと）と names（string の array、任意。省略時は名前付きバインディングなし）が含まれます
    • exports（string の array、任意）— このモジュールがエクスポートする名前
    • dynamic_imports（string の array、任意）— このモジュールが動的にインポートするモジュールパス

  {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