Enterprise Python AST-Driven Dead Code & Dependency Drift Purge Engine
数百万行のレガシーなPythonモノリスで「消してはいけない関数」を誤認し、本番環境をクラッシュさせた苦い経験はないだろうか。
この問題はDjangoやPyQtなどの巨大コードベースを扱うチームなら誰しもが直面する。静的解析ツール（vultureなど）をかけた結果、プラグイン機構ごと根こそぎ削除され、ImportErrorで全画面がクラッシュする事故は決して珍しい話ではない。
本記事では、過去の失敗事例から得た知見とAST解析による決定論的なデッドコード検出の仕組みを紹介する。
1. なぜ静的解析ツール（vulture等）単体では限界があるのか？
「使われていないコードを自動で探し出して削除する」——言葉にすれば簡単だが、エンタープライズ規模のPythonシステムにおいて、これを**「純粋な静的解析のみ」**で行うことは物理的・論理的に不可能に近い。
その最大の理由は、Pythonが持つ強力な**「動的解決（Dynamic Resolution）」**の機能にある。
-
動的インポートの壁:
importlib.import_module(f"plugins.{user_config}")のような文字列結合によるインポート。 -
メタプログラミングの罠:
__getattr__やsetattrを用いて実行時に生えるメソッド群。 - フレームワークのフック機構: Djangoのシグナルや、PyQtの動的なイベントバインディング。
既存のツール（vulture等）を安易に適用すると、これらの「実行時にならないと参照が確定しないコード」をすべて**「デッドコード（到達不能）」**と誤認してしまう。
その結果、「AIや自動化ツールが綺麗にしてくれました！」というプルリクエストをマージした直後に、本番環境が AttributeError や ImportError で大炎上する惨事を招くことになる。
2. 解決策：「ハイブリッド・セーフティ・フィルター」のアーキテクチャ
この「消したら本番が壊れるかもしれない」というシニアエンジニアの恐怖を取り除くため、我々は**「Enterprise Python AST-Driven Purge Engine」**を開発した。
マジカルな全自動削除や、LLMのハルシネーション（幻覚）に依存することを完全に拒絶し、以下の3フェーズからなる「ハイブリッド・セーフティ・フィルター」を採用している。
Phase 1: AST Deep Traversal（静的シンボルグラフの構築）
Python標準の ast モジュールを用いて、数百万行のコードベースを安全にチャンク分割しながらメモリパースする。クラス、関数、グローバル変数の「静的な参照グラフ（Symbol Graph）」を構築する。
Phase 2: Runtime Telemetry Merging（動的テレメトリの突合）
Phase 1で得た静的グラフに対し、本番環境やCIのテストランナーから収集した**動的テレメトリ（カバレッジレポートや、sys.settrace による関数呼び出しログ）**をマージする。
これにより、「静的には参照が見つからないが、実行時には呼ばれているプラグイン関数」を検知し、削除候補から除外する。
Phase 3: Safe Purge & Minimal Git Diff Generation
最終的に安全と確認されたノードのみをASTから削り落とし、人間がレビューしやすい最小限のGit Diff（パッチ）を生成する。
⚠️ 最重要の設計思想（RETAIN_DYNAMIC_RISK）
文字列結合のインポートや、メタクラスが絡む「動的解決リスクが高いコード」については、絶対に自動削除しない。これらは RETAIN_DYNAMIC_RISK タグを付与して隔離し、シニアエンジニアへのレビュー用コメントとしてPull Requestに警告を出すにとどめる。
3. 提供する真の価値：「コードの価値」から「時間の価値」へ
本エンジンは、「コードをただ綺麗にするためのおもちゃ」ではない。
巨大なレガシー環境において、使われているかどうかわからない関数を消すために、シニアエンジニアが grep で何時間もコードを追いかけ、影響調査に「丸2週間」を費やしているのが現場のリアルだ。
本パイプラインは、この**「丸2週間の無限の不安とデバッグ調査時間」を「数分」へ短縮するタイムマシン**である。
コードを消すのではなく、エンジニアが抱える「消したら壊れるかも」という心理的負荷と労務コストを完全に消し去るためのセーフティネットとして機能する。
4. 永続的保守・運用体制（CI追従）
一度作って終わりのツールでは意味がない。Pythonエコシステムの急速な変化に取り残されないよう、本エンジン自体も極めて堅牢な運用設計としている。
-
マルチバージョン差異の追従: Python 3.10〜3.13までのAST構造のマイナーチェンジ（
match-case構文の追加など）に対し、マルチバージョンのCIマトリクスビルドを常時回し、APIドリフトを自動検知。 - 回帰テストスイートの運用: 過去に「誤検知して本番をクラッシュさせかけた」エッジケース（特殊なPyQtフックなど）をすべてテストスイートに組み込み、二度と同じ失敗を起こさない回帰テストを徹底している。
おわりに
開発現場における真の技術的負債とは、汚いコードそのものではなく、それに触れることを恐れてチームの足が止まってしまうことにある。
「vultureで全消ししてクラッシュさせたトラウマ」を乗り越え、物理制約と泥臭い現実に向き合ったこのAST駆動パージエンジンが、あなたの開発現場から「バージョンアップ地獄の不安」を取り除けることを願っている。