deadpath

deadpath

コードベースには、誰も使っていないエクスポートが蓄積していきます。後に削除された呼び出し元のために書かれたヘルパー、「念のため」と残された定数、かつて何かがそこから名前をインポートしたために、今もバンドルに含まれているモジュール全体などです。deadpath は、証拠に基づいてこの疑問に答えます。モジュールのセット（各モジュールのパス、エクスポートする名前、インポートする名前）を渡すと、そのセット内のどこからもインポートされていないエクスポート名を特定します。

• モジュールごとの概要 — 各モジュールについて、未使用のエクスポート名、重複を除いたエクスポート総数、使用されているエクスポート数を示します。
• 未使用エクスポートの一覧 — すべての未使用エクスポートを{module, name}のペアで示し、クリーンアップリストや CI チェックにそのまま使えるように並べ替えます。
• セット全体の合計 — エクスポート総数、未使用数、およびセットのエクスポート範囲のうち未使用の割合を小数点以下 4 桁に丸めた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です。ここでは、legacyはsrc/util.tsからエクスポートされていますが、どこからもインポートされていないため、レポートは次のようになります。

{
  "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（配列、必須、1 件以上） — {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