refactor: パッケージ構造化 (error_formatter, json_repository)

Python教材価値向上リファクタリングの一環として:

- error_formatter.py → error_formatter/ パッケージ化
  - base.py: 共通基底クラス (Template Method)
  - config_errors.py, file_errors.py, etc.: カテゴリ別 (Composite)

- json_repository.py → json_repository/ パッケージ化
  - operations.py: CRUD操作
  - load_strategy.py: Strategy Pattern実装
  - chained_loader.py: Chain of Responsibility実装

- DESIGN_DECISIONS.md: 設計判断記録を追加

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: web-flow

EpisodicRAG/docs/dev/DESIGN_DECISIONS.md

@@ -0,0 +1,152 @@
+# 設計判断記録
+
+本ドキュメントは、EpisodicRAGプロジェクトにおける主要な設計判断とその根拠を記録する。
+エンタープライズPython開発の教材として、各判断の「なぜ」を明示することを目的とする。
+
+---
+
+## アーキテクチャ決定
+
+| 決定事項 | 検討した代替案 | 選択理由 |
+|---------|--------------|---------|
+| Clean Architecture 4層 | MVC, 単純なLayered | テスタビリティ、依存方向の制御 |
+| Strategy (LevelBehavior) | 継承階層, Switch文 | OCP準拠、新レベル追加時の変更最小化 |
+| Thin Facade (DigestConfig) | 直接アクセス, Thick Facade | シンプル化、重複排除、カプセル化 |
+| TypedDict | dataclass, NamedTuple | JSON互換性、段階的型付け、既存dictとの相互運用 |
+| Singleton (Registry) | DIコンテナ, グローバル変数 | ドメイン層のシンプルさ、テスト時のリセット可能性 |
+| Composite (ErrorFormatter) | 単一クラス, 関数群 | カテゴリ別責務分離、SRP準拠 |
+| Chain of Responsibility (TemplateLoader) | if-else連鎖, Switch | 戦略の追加・削除が容易、OCP準拠 |
+
+---
+
+## 各パターンの実装箇所
+
+### Strategy Pattern
+- **実装**: `domain/level_registry.py`
+- **目的**: 8階層（weekly〜centurial）ごとの振る舞いを交換可能に
+- **SOLID**: OCP（新レベル追加時に既存コード変更不要）
+
+### Facade Pattern
+- **実装**: `config/facade.py`
+- **目的**: 複雑な設定サブシステムへのシンプルなインターフェース
+- **設計判断**: Thin Facade（プロバイダを直接公開、重複プロパティ排除）
+
+### Repository Pattern
+- **実装**: `infrastructure/json_repository/`
+- **目的**: ファイルI/Oの抽象化、ビジネスロジックからの分離
+- **SOLID**: DIP（上位層がI/O詳細に依存しない）
+
+### Template Method Pattern
+- **実装**: `domain/error_formatter/base.py`
+- **目的**: パス正規化などの共通処理を基底クラスで定義
+- **SOLID**: DRY（コード重複の排除）
+
+### Composite Pattern
+- **実装**: `domain/error_formatter/__init__.py`
+- **目的**: カテゴリ別フォーマッタを統合インターフェースで提供
+- **SOLID**: SRP（各フォーマッタが単一カテゴリに責任）
+
+### Chain of Responsibility Pattern
+- **実装**: `infrastructure/json_repository/template_loader.py`
+- **目的**: テンプレートロード戦略の順次試行
+- **SOLID**: OCP（新戦略追加が容易）
+
+---
+
+## SOLID原則の実践箇所
+
+### Single Responsibility Principle (SRP)
+- `domain/error_formatter/`: エラーカテゴリごとに独立クラス
+- `infrastructure/json_repository/`: I/O、テンプレート、ユーティリティを分離
+- `config/`: 各プロバイダが単一責務（閾値、パス、ソース）
+
+### Open/Closed Principle (OCP)
+- `domain/level_registry.py`: 新レベル追加時に既存コード変更不要
+- `infrastructure/json_repository/template_loader.py`: 新戦略追加が容易
+
+### Liskov Substitution Principle (LSP)
+- `domain/error_formatter/base.py`: 全サブクラスが基底クラスの契約を満たす
+- `infrastructure/json_repository/template_loader.py`: 全戦略がLoadStrategyを満たす
+
+### Interface Segregation Principle (ISP)
+- `domain/protocols.py`: 必要最小限のProtocol定義
+- 各層の`__init__.py`: 必要なAPIのみをexport
+
+### Dependency Inversion Principle (DIP)
+- `interfaces/finalize_from_shadow.py`: コンストラクタインジェクション
+- 全層: 上位層は下位層の具象に依存しない
+
+---
+
+## レイヤー構造
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Interfaces Layer                      │
+│  (finalize_from_shadow.py, save_provisional_digest.py)  │
+│  外部からのエントリーポイント                              │
+└─────────────────────────────────────────────────────────┘
+                          ↓ 依存
+┌─────────────────────────────────────────────────────────┐
+│                   Application Layer                      │
+│  (shadow/, grand/, finalize/, tracking/)                │
+│  ユースケースの実装、ビジネスプロセスの調整                  │
+└─────────────────────────────────────────────────────────┘
+                          ↓ 依存
+┌─────────────────────────────────────────────────────────┐
+│                  Infrastructure Layer                    │
+│  (json_repository/, file_scanner.py, logging_config.py) │
+│  外部リソースへのアクセス（ファイル、ログ）                  │
+└─────────────────────────────────────────────────────────┘
+                          ↓ 依存
+┌─────────────────────────────────────────────────────────┐
+│                      Config Layer                        │
+│  (facade.py, threshold_provider.py, path_resolver.py)   │
+│  設定管理、パス解決                                       │
+└─────────────────────────────────────────────────────────┘
+                          ↓ 依存
+┌─────────────────────────────────────────────────────────┐
+│                      Domain Layer                        │
+│  (types.py, constants.py, exceptions.py, protocols.py)  │
+│  ビジネスルール、型定義、例外（外部依存なし）                │
+└─────────────────────────────────────────────────────────┘
+```
+
+**重要な制約**: 依存は常に下方向のみ。上位層が下位層に依存し、逆は許可されない。
+
+---
+
+## TypedDict vs dataclass の選択
+
+| 観点 | TypedDict | dataclass |
+|-----|-----------|-----------|
+| JSON互換性 | ネイティブ対応 | 変換が必要 |
+| 既存dictとの相互運用 | シームレス | 明示的変換 |
+| 型チェック | 静的のみ | 静的＋実行時 |
+| イミュータビリティ | 制御不可 | frozen=True |
+| デフォルト値 | total=Falseで対応 | 直接サポート |
+
+**選択理由**: EpisodicRAGはJSONファイルを多用するため、TypedDictの方が自然。
+
+---
+
+## Singleton vs DI の選択
+
+| 観点 | Singleton | Dependency Injection |
+|-----|-----------|---------------------|
+| シンプルさ | 高 | 中〜低 |
+| テスタビリティ | reset関数で対応 | 高 |
+| グローバル状態 | あり | なし |
+| 設定変更 | 難しい | 容易 |
+
+**選択理由**: ドメイン層は外部依存を持たないため、シンプルなSingletonで十分。
+テスト用に`reset_level_registry()`を提供してテスタビリティを確保。
+
+---
+
+## 参考リンク
+
+- [Clean Architecture (Robert C. Martin)](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)
+- [SOLID Principles](https://en.wikipedia.org/wiki/SOLID)
+- [Design Patterns (GoF)](https://en.wikipedia.org/wiki/Design_Patterns)
+- [Python typing.TypedDict](https://docs.python.org/3/library/typing.html#typing.TypedDict)

EpisodicRAG/scripts/application/finalize/persistence.py

@@ -97,7 +97,7 @@ def save_regular_digest(
             save_json(final_path, as_dict(regular_digest))
         except IOError as e:
             formatter = get_error_formatter()
-            raise FileIOError(formatter.file_io_error("save", final_path, e))
+            raise FileIOError(formatter.file.file_io_error("save", final_path, e))
 
         log_info(f"RegularDigest saved: {final_path}")
         return final_path
@@ -120,7 +120,7 @@ def update_grand_digest(
         overall_digest = regular_digest.get("overall_digest")
         if not overall_digest or not is_valid_dict(overall_digest):
             formatter = get_error_formatter()
-            raise DigestError(formatter.validation_error("RegularDigest", "has no valid overall_digest", None))
+            raise DigestError(formatter.validation.validation_error("RegularDigest", "has no valid overall_digest", None))
         # GrandDigestManager.update_digestは例外を投げる（失敗時）
         self.grand_digest_manager.update_digest(level, new_digest_name, overall_digest)
 

EpisodicRAG/scripts/application/finalize/provisional_loader.py

@@ -87,7 +87,7 @@ def _load_provisional(self, provisional_path: Path) -> Tuple[List[IndividualDige
 
         if not is_valid_dict(provisional_data):
             formatter = get_error_formatter()
-            raise DigestError(formatter.invalid_type(provisional_path.name, "dict", provisional_data))
+            raise DigestError(formatter.validation.invalid_type(provisional_path.name, "dict", provisional_data))
 
         individual_digests = provisional_data.get("individual_digests", [])
         log_debug(f"{LOG_PREFIX_STATE} loaded_digests_count: {len(individual_digests)}")

EpisodicRAG/scripts/application/finalize/shadow_validator.py

@@ -56,19 +56,19 @@ def _collect_validation_errors(
         # 型チェック
         formatter = get_error_formatter()
         if not is_valid_list(source_files):
-            fatal_errors.append(formatter.invalid_type("source_files", "list", source_files))
+            fatal_errors.append(formatter.validation.invalid_type("source_files", "list", source_files))
             return fatal_errors, warnings, numbers
 
         # 空チェック
         if not source_files:
-            fatal_errors.append(formatter.empty_collection(f"Shadow digest for level '{level}'"))
+            fatal_errors.append(formatter.validation.empty_collection(f"Shadow digest for level '{level}'"))
             return fatal_errors, warnings, numbers
 
         # ファイル名検証と番号抽出を1ループで実行
         for i, filename in enumerate(source_files):
             if not isinstance(filename, str):
                 fatal_errors.append(
-                    formatter.invalid_type(f"filename at index {i}", "str", filename)
+                    formatter.validation.invalid_type(f"filename at index {i}", "str", filename)
                 )
                 continue
 
@@ -142,7 +142,7 @@ def _validate_title(self, weave_title: str) -> None:
         """
         if not weave_title or not weave_title.strip():
             formatter = get_error_formatter()
-            raise ValidationError(formatter.empty_collection("weave_title"))
+            raise ValidationError(formatter.validation.empty_collection("weave_title"))
 
     def _fetch_shadow_digest(self, level: str) -> OverallDigestData:
         """
@@ -162,7 +162,7 @@ def _fetch_shadow_digest(self, level: str) -> OverallDigestData:
         if shadow_digest is None:
             log_info("Run 'python shadow_grand_digest.py' to update shadow first")
             formatter = get_error_formatter()
-            raise DigestError(formatter.digest_not_found(level, "shadow"))
+            raise DigestError(formatter.digest.digest_not_found(level, "shadow"))
 
         return shadow_digest
 
@@ -178,7 +178,7 @@ def _validate_shadow_format(self, shadow_digest: Any) -> None:
         """
         if not is_valid_dict(shadow_digest):
             formatter = get_error_formatter()
-            raise ValidationError(formatter.invalid_type("shadow digest", "dict", shadow_digest))
+            raise ValidationError(formatter.validation.invalid_type("shadow digest", "dict", shadow_digest))
 
     def validate_and_get_shadow(self, level: str, weave_title: str) -> OverallDigestData:
         """

EpisodicRAG/scripts/application/grand/grand_digest.py

@@ -146,16 +146,16 @@ def update_digest(
         formatter = get_error_formatter()
         # 型チェック
         if not is_valid_dict(grand_data):
-            raise DigestError(formatter.invalid_type("GrandDigest.txt", "dict", grand_data))
+            raise DigestError(formatter.validation.invalid_type("GrandDigest.txt", "dict", grand_data))
 
         if "major_digests" not in grand_data:
-            raise DigestError(formatter.config_section_missing("major_digests"))
+            raise DigestError(formatter.config.config_section_missing("major_digests"))
 
         available_levels = list(grand_data["major_digests"].keys())
         log_debug(f"{LOG_PREFIX_VALIDATE} available_levels: {available_levels}")
 
         if level not in grand_data["major_digests"]:
-            raise DigestError(formatter.unknown_level(level))
+            raise DigestError(formatter.config.unknown_level(level))
 
         # overall_digestを更新（完全なオブジェクトとして保存）
         log_debug(f"{LOG_PREFIX_STATE} updating overall_digest for level={level}")

EpisodicRAG/scripts/application/validators.py

@@ -114,13 +114,13 @@ def validate_source_files(files: Any, context: str = "source_files") -> List[str
     """
     formatter = get_error_formatter()
     if files is None:
-        raise ValidationError(formatter.validation_error(context, "cannot be None", None))
+        raise ValidationError(formatter.validation.validation_error(context, "cannot be None", None))
 
     if not isinstance(files, list):
-        raise ValidationError(formatter.invalid_type(context, "list", files))
+        raise ValidationError(formatter.validation.invalid_type(context, "list", files))
 
     if not files:
-        raise ValidationError(formatter.empty_collection(context))
+        raise ValidationError(formatter.validation.empty_collection(context))
 
     return files
 

EpisodicRAG/scripts/config/__init__.py

@@ -5,14 +5,27 @@
 
 Plugin自己完結版：Plugin内の.claude-plugin/config.jsonから設定を読み込む
 
-Architecture:
-    DigestConfig は薄い Facade として機能し、以下のコンポーネントに委譲:
-    - ConfigLoader: 設定ファイルの読み込み
-    - PathResolver: パス解決
-    - ThresholdProvider: 閾値管理
-    - LevelPathService: レベル別パス管理
-    - SourcePathResolver: ソースパス解決
-    - ConfigValidator: 設定とディレクトリ構造の検証
+## 設計意図
+
+ARCHITECTURE: Thin Facade Pattern
+DigestConfigは薄いFacadeとして機能し、内部コンポーネントに委譲。
+各コンポーネントは単一責任（SRP）を持つ。
+
+| コンポーネント | 責務 |
+|---------------|------|
+| ConfigLoader | 設定ファイルの読み込み |
+| PathResolver | パス解決 |
+| ThresholdProvider | 閾値管理 |
+| LevelPathService | レベル別パス管理 |
+| SourcePathResolver | ソースパス解決 |
+| ConfigValidator | 設定とディレクトリ構造の検証 |
+
+## 閾値アクセス方法
+
+ARCHITECTURE: コンポーネント公開による責務明確化
+閾値は`threshold`プロパティ経由でアクセス:
+    config.threshold.get_threshold("weekly")
+    config.threshold.weekly_threshold
 
 Usage:
     from config import DigestConfig
@@ -112,7 +125,7 @@ def __init__(self, plugin_root: Optional[Path] = None):
 
         except (PermissionError, OSError) as e:
             formatter = get_error_formatter()
-            raise ConfigError(formatter.initialization_failed("configuration", e)) from e
+            raise ConfigError(formatter.config.initialization_failed("configuration", e)) from e
 
     # =========================================================================
     # Context Manager Support
@@ -256,53 +269,37 @@ def validate_directory_structure(self) -> List[str]:
         """ディレクトリ構造の検証"""
         return self._directory_validator.validate_directory_structure()
 
-    def get_threshold(self, level: str) -> int:
-        """指定レベルのthresholdを動的に取得"""
-        return self._threshold_provider.get_threshold(level)
-
     # =========================================================================
-    # 明示的プロパティ（IDE補完対応、ThresholdProviderに委譲）
+    # コンポーネント公開プロパティ
     # =========================================================================
 
     @property
-    def weekly_threshold(self) -> int:
-        """週次thresholdを取得"""
-        return self._threshold_provider.weekly_threshold
-
-    @property
-    def monthly_threshold(self) -> int:
-        """月次thresholdを取得"""
-        return self._threshold_provider.monthly_threshold
-
-    @property
-    def quarterly_threshold(self) -> int:
-        """四半期thresholdを取得"""
-        return self._threshold_provider.quarterly_threshold
-
-    @property
-    def annual_threshold(self) -> int:
-        """年次thresholdを取得"""
-        return self._threshold_provider.annual_threshold
+    def threshold(self) -> ThresholdProvider:
+        """
+        閾値プロバイダーへのアクセス
 
-    @property
-    def triennial_threshold(self) -> int:
-        """3年thresholdを取得"""
-        return self._threshold_provider.triennial_threshold
+        ARCHITECTURE: コンポーネント公開パターン
+        Facadeがラッパーメソッドを提供する代わりに、
+        内部コンポーネントを直接公開することで:
+        - コードの重複を排除
+        - IDE補完がThresholdProviderの全メソッドに対応
+        - 責務の所在が明確
 
-    @property
-    def decadal_threshold(self) -> int:
-        """10年thresholdを取得"""
-        return self._threshold_provider.decadal_threshold
+        Usage:
+            config.threshold.get_threshold("weekly")
+            config.threshold.weekly_threshold
+            config.threshold.monthly_threshold
+        """
+        return self._threshold_provider
 
-    @property
-    def multi_decadal_threshold(self) -> int:
-        """数十年thresholdを取得"""
-        return self._threshold_provider.multi_decadal_threshold
+    def get_threshold(self, level: str) -> int:
+        """
+        指定レベルのthresholdを動的に取得
 
-    @property
-    def centurial_threshold(self) -> int:
-        """100年thresholdを取得"""
-        return self._threshold_provider.centurial_threshold
+        Note:
+            後方互換性のため維持。新規コードは config.threshold.get_threshold() を推奨。
+        """
+        return self._threshold_provider.get_threshold(level)
 
     def show_paths(self) -> None:
         """パス設定を表示（デバッグ用）"""