1. 導入：なぜ循環参照の検知が重要なのか
開発が進むにつれ、モジュール間の依存関係が複雑化し、いつの間にか「AがBを呼び、BがAを呼ぶ」といった循環参照（Circular Dependency）が発生してしまうことは珍しくありません。これは単なるコードの汚れではなく、予期せぬ実行時エラーや、テストの困難化、バンドルサイズの無駄な肥大化を招く「設計の腐敗」の兆候です。本記事では、静的解析ツールを用いて、CI/CDパイプライン上で循環参照を自動検知し、健全な依存関係を維持する手法を解説します。
2. 基礎知識：循環参照が引き起こす問題
循環参照とは、モジュール同士が互いに依存し合っている状態を指します。
・実行時の不具合: JavaScript/TypeScript環境では、初期化順序の問題で未定義のモジュールを参照し、実行時エラーになることがあります。
・テストの困難化: 依存関係が複雑なため、特定のクラスや関数だけを切り出してテストすることが不可能になります。
・疎結合の崩壊: モジュールが密結合になることで、機能追加や修正が他のモジュールに波及し、保守コストが爆発的に増大します。
3. 実装/解決策：madgeを利用した自動検知
循環参照の検知には、Node.js環境でデファクトスタンダードとなっている「madge」というツールを活用します。madgeは、プロジェクト内の依存関係を可視化し、循環している箇所をリストアップするCLIツールです。これをCI環境に組み込むことで、循環参照を含むコードがリポジトリにマージされるのを物理的に防ぐことができます。
4. サンプルプログラム：CIへの導入手順
まずはプロジェクトにmadgeをインストールします。
npm install –save-dev madge
以下は、実行時に循環参照があればエラーを返し、CIを失敗させるためのコマンド例です。
プロジェクト内の循環参照を検知し、存在すれば終了コード1を返して異常終了させる
–extensions で対象の拡張子を指定します
npx madge –circular –extensions ts ./src
もし特定のファイルやディレクトリを除外したい場合は、以下のように設定を追加してください。
ユニットテストファイルを除外して循環参照をチェックする例
npx madge –circular –extensions ts –exclude “.\.test\.ts” ./src
【 package.json への組み込み例 】
チーム開発において、開発者が手動で実行し忘れないよう、スクリプトに登録しておくのが一般的です。
{
“scripts”: {
“lint:circular”: “madge –circular –extensions ts ./src”
}
}
5. 応用・注意点：現場での運用のコツ
・段階的な導入: 既存の大規模プロジェクトに導入すると、数百の循環参照が見つかることがあります。まずは「新規の循環参照を許さない」という運用から始め、少しずつリファクタリングで解消していくのが現実的です。
・依存関係の可視化: madgeは循環参照の検知だけでなく、依存関係を画像ファイル（SVGなど）として出力する機能もあります。ドキュメント作成やアーキテクチャレビューに活用しましょう。
・根本的な解決策: 循環参照が見つかった場合、安易にコードを修正するのではなく、「共通の依存先を切り出す」「依存の方向を一方向に整理する」といったモジュール設計の見直し（リファクタリング）を優先してください。循環参照は、設計上のミスを伝える重要なサインだからです。