typescript-circular-dependency

此技能提供了一套系統化的方法，用於診斷和修復 TypeScript 與 JavaScript 專案中的循環依賴問題。當模組之間直接或間接互相導入時，會發生循環依賴，導致執行時因模組尚未完成初始化而使導出值變為 undefined。此工具適用於在複雜模組化代碼庫中工作的軟體工程師，他們常遇到因導入順序不同而導致間歇性執行時 TypeError 或 ReferenceError 的問題。

• 使用 madge 函式庫進行自動循環偵測，以視覺化並識別出問題的依賴圖。

• 針對常見架構問題（如服務對服務循環、index.ts 桶裝檔案污染、過度的類型與數值耦合）提供基於模式的診斷策略。

• 實際解決方案，包括依賴注入、將共用類型提取至專用介面檔案，以及使用動態導入來打破同步依賴鏈。

• 實施僅類型導入（Type-only imports），以消除僅供介面使用的依賴項在執行時的負擔。

• 提供 CI/CD 整合指南，透過將循環依賴檢查嵌入自動化構建腳本或 ESLint 配置中，防止未來的迴歸問題。

• 目標情境包含執行時 ReferenceErrors、意外的 undefined 導出，以及儘管編譯有效但測試卻因模組解析問題而失敗的情況。

• 建議用於使用 Jest、Vitest、Webpack 或 Vite 等框架的開發者，這些框架的模組解析時機與標準 TS 編譯不同。

• 使用者需提供源目錄作為輸入，並準備好將共享邏輯重構為解耦模組。

• 限制條件包括解耦緊密耦合服務時可能需要的重構工作，以及在大型專案中維護一致導入模式的需求。