Elixir 循環依存関係

使用時機

このスキルは、ユーザーが循環依存関係の確認または削除を明確に要求した場合のみに適用してください(例：「循環をチェックしたい」「循環依存関係を削除したい」「xref 循環エラーを修正したい」)。

前提条件：Elixir のバージョン

循環検出が正しく機能するのは Elixir 1.19 以上のみです。循環チェックを実行する前に：

1. バージョン確認：elixir -v または mix run -e 'IO.inspect(System.version())'をプロジェクト内で実行します。
2. バージョンが 1.19 未満の場合、停止し、確実な循環検出のために Elixir 1.19+ へのアップグレードが必要であることをユーザーに伝えてください。

循環の検出

プロジェクトルートから両方のコマンドを実行します。まずはじめに許容値を緩めた状態から始め、その後厳しくしていきます：

mix xref graph --format cycles --label compile-connected --fail-above 3
mix xref graph --format cycles --label compile --fail-above 3

• compile-connected：コンパイル時依存関係グラフ内の循環（循環でコンパイルされるモジュール）。
• compile：同じグラフですが、ラベルが異なります。両方実行する必要があります。
• --fail-above N：循環数が N を超える場合に終了コードが失敗します。最初は 3 を使用し、目標は 0 です。

循環を失敗させずにリストアップします（検査用）。--fail-above を省略するか高い値に設定してください：

mix xref graph --format cycles --label compile-connected
mix xref graph --format cycles --label compile

目標：両方のコマンドで --fail-above 0 に到達（循環なし）。

ワークフロー

1. Elixir バージョン確認（≥ 1.19 である必要があります）。
2. 基準値を確立：両方の xref コマンドを --fail-above 3（またはプロジェクトの現在の設定）で実行します。循環数とどのモジュールが循環に関わっているかをメモします。
3. 循環を検査：--fail-above なしで実行して完全な循環出力を確認します。削除すれば循環が壊れるエッジ（モジュール A → モジュール B）の最小セットを特定します。
4. 最小限の変更セットを計画：
   • 大規模なリファクタリングより単一の依存関係を壊すこと（例：共有コードを新しいモジュールに移動し、両方で依存）を優先します。
   • ヘルパーモジュールは許可されます（最小限の変更が得られる場合）：共有ロジックを新しいモジュールに抽出し、循環参加者がそれに依存することで循環を壊します。
   • 重複を避けます。既存リポジトリガイドライン（例：AGENTS.md、.cursor ルール）と既存のコードパターンに従います。
5. 実装：選択した変更を加えてから、両方の xref コマンドを --fail-above 0（または段階的に 3 → 0）で再実行します。
6. 検証：mix compile --warnings-as-errors、テスト、およびプロジェクト lint（例：mix lint または定義されている場合は mix cyclecheck）を実行します。

最小限の変更戦略

戦略	使用時機
ヘルパーモジュールを抽出	循環内の 2 つ以上のモジュールが同じロジックを必要とします。循環に戻る依存関係がない新しいモジュールに抽出します。
コードを下に移動	モジュール A の関数をモジュール B に移動して、A が B に依存しなくなる（またはその逆）ようにし、循環を壊します。
依存関係を反転	A が B を使用し、B が A を使用する場合、1 つの使用がコールバック、オプション、またはデータ構造に置き換えられるかどうかを確認し、1 方向だけが残るようにします。
モジュールを分割	1 つのモジュールが 2 つの異なる責任を持ち、2 つの循環に参加している場合。2 つのモジュールに分割して循環を壊します。

最小限のコード変更で循環を削除し、新しい重複を導入しないオプションを選択してください。

プロジェクト統合

プロジェクトが mix.exs に cyclecheck（またはそれに類するもの）タスクを持っている場合、変更後に使用します：

mix cyclecheck

循環が解消されたら、両方の xref コマンドをターゲット --fail-above 0 で実行していることを確認します。

サマリーチェックリスト

• Elixir バージョン ≥ 1.19 を確認
• compile-connected と compile の両方の xref 循環コマンドを実行
• 目標：両方で --fail-above 0
• 最小限の変更セット（ヘルパーモジュール可）
• コード重複なし。リポジトリガイドラインに従う
• 変更後に mix compile、テスト、lint がパス