inspect-structure

inspect-structure — コード品質と構造的負債の検査ツール

ドメイン評価基準

1. 対象範囲と運用上の境界

• 構造的負債と構文・書式：分析対象は、モジュール、クラス、メソッドの各階層における構造、OOP、認知的負債に厳密に限定します。空白、セミコロン、スタイルに関する細かな指摘は、すべてネイティブのリンターに委ねます。
• アーキテクチャ上の凝集性と行数の基準（LOC / wc -l）：生の行数（LOC）や wc -l を、「God Class」の主な指標や判定基準として使用することを禁止します。ファイルの長さではなく、構造的な凝集性、アクターの境界、I/O の結合度を評価します。宣言的な UI コンポーネント階層（マークアップ、レイアウトツリー、レスポンシブなスタイル設定）や設定・トークンレジストリは、OOP の God Class と区別します。単一のプレゼンター／コントローラーに紐付いた大規模な宣言的ビューコンポーネントはアーキテクチャ上妥当ですが、永続化、ネットワーク通信、ドメイン状態を密接に絡めた小規模なクラスは危険な God Class です。
• アーキテクチャの形態とビジネスロジック：構造的な凝集性と保守性のみを監査します。信頼できる仕様がない限り、ドメインのビジネスルール、価格計算ロジック、数式は評価しません（バグの切り分けは /diagnose に、仕様との乖離は /assay に回します）。
• 読み取り専用の監査とコードの変更：構造化された検査報告書のみを作成します。ディスク上のファイルの変更、コード差分の生成、自動リファクタリングの適用は禁止します（修正計画は /changeset に回します）。

2. 構造検査の観点

1. クラスの凝集性と SRP（God Class）

   • 評価基準：
     • 凝集度の欠如（LCOM）：メソッドが共有状態のまとまりを操作しているか、それとも互いに独立した状態群に分かれているかを評価します。
     • 責務とアクターのクラスタリング：クラスが複数の外部アクター、異なるライフサイクル、または無関係なサブシステムの関心事（例：ストレージ、通信、ハードウェアドライバー）を担っているかを確認します。
     • 境界の分離：プレゼンテーション／UI コンポーネントが、ドメインコントローラー、プレゼンター、状態通知機構に委譲せず、直接 I/O を実行したり、永続化を管理したり、通信リクエストを送信したりしていないかを確認します。
   • 真のアンチパターン：プレゼンテーションコンポーネントに直接 I/O や永続化を混在させること、1 つのサービスで複数の独立した集約ルートを調整すること、単一責任の原則（複数のアクターまたは変更要因）に違反すること。
   • 避けるべき誤検知：行数（LOC）だけを根拠に God Class と判定してはいけません。単一の一貫した責務に紐付いている限り、大規模な宣言的 UI ツリー、ビューのスタイル設定、シリアライゼーションテーブル、設定・トークンレジストリは許容します。
   • 改善策：単一責任を持つドメインサービス、値オブジェクト、コントローラー／プレゼンター、またはストラテジー委譲先に分割します。
   • 短いコード例：

     問題（OOP の God Class）：    class OrderManager { calculateTax(); sendEmail(); saveToDb(); renderPdf(); }
     改善策：                     class OrderService は TaxCalculator、OrderMailer、OrderRepository、PdfRenderer に処理を委譲します。
     
     問題（UI 境界の漏れ）：      class ProfileView { render() { http.get("/user"); db.save(); } }
     改善策：                     ProfileView は ProfileController に紐付き、コントローラーが UserService と Repository を調整します。
     

2. メソッドとフローの複雑さ（長いメソッド／深いネスト）

   • 問題：管理しやすい長さを超えるメソッド、3 階層以上の制御フローネスト、アローアンチパターン、または高い認知負荷。
   • 改善策：条件をガード節に反転し、ネストしたブロックを平坦化し、単一のタスクに集中する小さなヘルパーサブルーチンに分割します。
   • 短いコード例：

     問題：  void process() { if (a) { while (b) { if (c) { try { ... } } } } }
     改善策：早期リターンにガード節を使い、ループの本体をプライベートなサブルーチンに切り出します。
     

3. 体系的な重複（マクロおよびミクロの DRY）

   • 問題点：複数のクラス、ファイル、メソッドにまたがって、アルゴリズム処理、複数ステップの検証手順、エラー処理の一連の流れがコピー＆ペーストされています。
   • 対策：共通ルールを純粋関数または組み合わせ可能なヘルパーに切り出します。重複するロジックがライフサイクル、依存関係、所有権を共有する場合に限り、基底となる抽象化を検討します。各呼び出し箇所では、それぞれのトランザクション境界の検証を維持します。
   • ミクロの例：

     Smell:  ServiceAとServiceBが、それぞれのトランザクション内で同一の判断ロジックを複製しています。
     Remedy: 状態のスナップショットを受け取る純粋関数に切り出します。各サービスは、それぞれのトランザクション、ロック、状態の読み取りを維持します。
     

4. 結合とカプセル化の漏出

   • 問題点：外部クラスの内部データを操作するメソッド（Feature Envy）、またはゲッターを通じて変更可能な内部コレクションを直接公開するクラスです。
   • 対策：「Tell, Don't Ask」を適用し、状態の変更をドメインメソッドでカプセル化します。不変のスナップショットまたは防御的コピーを返します。
   • ミクロの例：

     Smell:  if (order.getCustomer().getAddress().getCountry().equals("US")) { ... }
     Remedy: if (order.isDomesticDelivery()) { ... }
     

5. ポリモーフィズムとストラテジーの不足（分散した分岐）

   • 問題点：複数のクラスに散在する並行したswitch(type)やif (type == A)の連鎖により、バリアントの変更時にShotgun Surgeryが発生します。
   • 対策：バリアントが独立して進化し、新しいバリアントの追加に複数ファイルの編集が必要になる場合は、Strategyまたはポリモーフィズムを検討します。分岐が1か所にまとまった単一のポリシーのケースであれば、明示的な条件分岐を優先します。切り出しの前に、凝集度と変更コストを評価します。
   • ミクロの例：

     Smell:  PaymentService、InvoiceService、EmailServiceが、それぞれ並行したswitch (user.getPlanTier())を保持しています。
     Remedy: ティアごとの動作をPlanTier戦略にカプセル化します（新しいティアごとに、独立した3つのサービスを同期して変更します）。
     

6. 堅牢性とリソース管理

   • 問題点：空のcatchブロックでエラーを握りつぶす、またはクリーンアップ用フックのないストリーム、データベース接続ハンドル、イベントリスナーを管理していません。
   • 対策：コンテキスト情報を付けて明示的に処理または再スローします。リソースのライフサイクルは、決定的な破棄ブロック（defer、finally、using）内にカプセル化します。
   • ミクロの例：

     Smell:  try { connect(); } catch (Exception e) {}
     Remedy: try { connect(); } catch (Exception e) { logger.error("DB connection failed", e); throw new ServiceUnavailableException(e); }
     

標準出力契約

# Structural Inspection Dossier: <Target Scope / Module>

## 1. Executive Summary
- **Target Inspected**: `<file_or_directory_path>`
- **Health Rating**: <CLEAN | MODERATE_DEBT | CRITICAL_DEBT>
- **Primary Bottleneck**: <Single-sentence summary of greatest structural risk>

## 2. Technical Debt Catalog

### [<CRITICAL | MAJOR | MINOR>] <Dimension Name>: `<Target Entity / Symbol>`
- **Location**: [<file>#L<N>-L<M>](file:///path/to/file#L<N>-L<M>)
- **Smell**: <Observable anti-pattern description and maintainability impact>
- **Remedy**: <Exact architectural decomposition or extraction path>

*(Repeat for each distinct structural finding; emit 'No structural code smells observed across rubric dimensions' if clean)*

振り分け

• 複数ファイルにわたる構造的リファクタリング、Godクラスの分解、または共通抽象化の切り出し →（via /changeset）。
• 実行時の機能的なバグやテストの失敗が疑われる場合 →（via /diagnose）。

実行プロトコル

フェーズ 1：対象範囲のトリアージとマクロレベルの把握

1. 対象パス（file、directory、またはsubsystem）を取り込みます。
2. シンボルおよびファイル用ツールを使って、主要な構造上のアンカー（クラス、モジュールのエントリーポイント、共通ユーティリティ）を特定します。

フェーズ 2：規模に応じた調査

• ターン内での実行（10ファイル未満、または凝集度の高いモジュール）：評価基準の各項目に照らして、コードを直接監査します。
• サブエージェントへの分散（複数のパッケージにまたがる広範なサブシステム、またはリポジトリ）：分割した範囲、または呼び出し元が指定した予算に応じて、researchサブエージェントを動的に並行起動します（役割：Structural Inspector (<Slice>)）。範囲の座標、特定済みのアンカー、ドメイン評価基準、標準出力契約を初期情報として渡します。

フェーズ 3：統合とターン終了ゲート（集約）

1. サブエージェントの調査結果を統合・重複排除し、標準出力契約にまとめます。
2. 最終的な健全性評価を割り当てます：
   • CLEAN：評価基準に違反する構造上の欠陥がありません。
   • MODERATE_DEBT：カプセル化の漏れ、散在する条件分岐、または軽微な重複が局所的にあります。
   • CRITICAL_DEBT：神クラス、サブシステムをまたぐコピー＆ペースト、またはシステム全体に及ぶリソースリークが蔓延しています。
3. 完成した検査記録を会話ストリームに出力し、ただちにターンを終了します。