@k2works/claude-code-booster 3.0.0 → 3.1.0

package/lib/assets/docs/article/getting-start-tdd/ruby/09-solid-principles-and-module-design.md

@@ -0,0 +1,196 @@
+# 第 9 章: SOLID 原則とモジュール設計
+
+## 9.1 はじめに
+
+前章までに多くのデザインパターンを適用しましたが、すべてのクラスが 1 つのファイルに詰め込まれた状態です。この章では **SOLID 原則** の観点からコードを検証し、責務に基づいた **モジュール設計** を行います。
+
+## 9.2 SOLID 原則の検証
+
+### 単一責任原則（SRP: Single Responsibility Principle）
+
+> クラスが変更される理由は一つでなければならない
+
+| クラス | 責務 | 変更理由 |
+|--------|------|---------|
+| `FizzBuzzValue` | FizzBuzz の結果値を表現 | 値の表現方法が変わるとき |
+| `FizzBuzzList` | FizzBuzz の結果コレクションを管理 | コレクション操作が変わるとき |
+| `FizzBuzzType01` | タイプ 1 の変換ルール | タイプ 1 のルールが変わるとき |
+| `FizzBuzzType02` | タイプ 2 の変換ルール | タイプ 2 のルールが変わるとき |
+| `FizzBuzzType03` | タイプ 3 の変換ルール | タイプ 3 のルールが変わるとき |
+| `FizzBuzzValueCommand` | 単一値の生成操作 | 値の生成方法が変わるとき |
+| `FizzBuzzListCommand` | リストの生成操作 | リストの生成方法が変わるとき |
+
+各クラスが 1 つの責務を持ち、変更理由は 1 つです。SRP を満たしています。
+
+### 開放閉鎖原則（OCP: Open-Closed Principle）
+
+> ソフトウェアエンティティは拡張に対して開いていて、修正に対して閉じている
+
+新しいタイプ（例: タイプ 4）を追加する場合:
+
+1. `FizzBuzzType04` クラスを **新規作成** する
+2. `FizzBuzzType.create()` の case 文に 1 行 **追加** する
+
+既存の `FizzBuzzType01`〜`03` は一切変更しません。OCP を満たしています。
+
+### 依存関係逆転の原則（DIP: Dependency Inversion Principle）
+
+> 上位レベルのモジュールは下位レベルのモジュールに依存してはならない。両方とも抽象に依存すべき
+
+```
+FizzBuzzValueCommand ──→ FizzBuzzType (基底クラス)
+FizzBuzzListCommand  ──→ FizzBuzzType (基底クラス)
+                              ↑
+                    FizzBuzzType01, Type02, Type03
+```
+
+- コマンド（上位）は基底クラス `FizzBuzzType` に依存
+- 具体的な Type01〜03 には直接依存しない
+- DIP を満たしています
+
+## 9.3 モジュール設計
+
+### 設計方針
+
+責務に基づいて 3 つのレイヤーに分割します。
+
+| レイヤー | 配置先 | 責務 |
+|---------|-------|------|
+| **ドメインモデル** | `domain/model/` | 値オブジェクト、コレクション |
+| **ドメインタイプ** | `domain/type/` | ビジネスルール（FizzBuzz 変換） |
+| **アプリケーション** | `application/` | 操作の実行（コマンド） |
+
+### ディレクトリ構成
+
+```
+lib/
+└── fizz_buzz/
+    ├── fizz_buzz.rb                      (バレルファイル: 全 require)
+    ├── domain/
+    │   ├── model/
+    │   │   ├── fizz_buzz_value.rb        (FizzBuzzValue)
+    │   │   └── fizz_buzz_list.rb         (FizzBuzzList)
+    │   └── type/
+    │       ├── fizz_buzz_type.rb         (FizzBuzzType 基底 + create)
+    │       ├── fizz_buzz_type_01.rb      (FizzBuzzType01)
+    │       ├── fizz_buzz_type_02.rb      (FizzBuzzType02)
+    │       └── fizz_buzz_type_03.rb      (FizzBuzzType03)
+    └── application/
+        ├── fizz_buzz_command.rb          (FizzBuzzCommand モジュール)
+        ├── fizz_buzz_value_command.rb    (FizzBuzzValueCommand)
+        └── fizz_buzz_list_command.rb     (FizzBuzzListCommand)
+```
+
+### 依存関係
+
+```
+application/ ──→ domain/type/ ──→ domain/model/
+     ↓                ↓                 ↓
+  コマンド          タイプ            値・コレクション
+```
+
+- `domain/model/` は他のモジュールに依存しない（最も安定）
+- `domain/type/` は `domain/model/` のみに依存
+- `application/` は `domain/type/` と `domain/model/` に依存
+
+### バレルファイル（fizz_buzz.rb）
+
+Ruby では `require_relative` を使ったバレルファイルで、モジュールの公開 API を集約します。
+
+```ruby
+# lib/fizz_buzz/fizz_buzz.rb
+# frozen_string_literal: true
+
+require_relative 'domain/model/fizz_buzz_value'
+require_relative 'domain/model/fizz_buzz_list'
+require_relative 'domain/type/fizz_buzz_type'
+require_relative 'domain/type/fizz_buzz_type_01'
+require_relative 'domain/type/fizz_buzz_type_02'
+require_relative 'domain/type/fizz_buzz_type_03'
+require_relative 'application/fizz_buzz_command'
+require_relative 'application/fizz_buzz_value_command'
+require_relative 'application/fizz_buzz_list_command'
+```
+
+利用側は 1 つの require パスですべてのクラスにアクセスできます:
+
+```ruby
+require_relative '../lib/fizz_buzz/fizz_buzz'
+```
+
+**require の順序が重要**: `FizzBuzzValue` → `FizzBuzzList` → `FizzBuzzType` → サブクラス → `FizzBuzzCommand` → コマンド実装の順に読み込む必要があります。これは Ruby が定数を参照する時点でクラスが定義済みである必要があるためです。
+
+## 9.4 テストの再編成
+
+テストもモジュール構造に合わせて分割します。
+
+```
+test/
+├── test_helper.rb
+└── fizz_buzz/
+    ├── domain/
+    │   ├── model/
+    │   │   ├── fizz_buzz_value_test.rb
+    │   │   └── fizz_buzz_list_test.rb
+    │   └── type/
+    │       └── fizz_buzz_type_test.rb
+    └── application/
+        └── fizz_buzz_command_test.rb
+```
+
+### テスト実行結果
+
+```bash
+$ bundle exec rake test
+Started with run options --seed 1052
+
+22 tests, 27 assertions, 0 failures, 0 errors, 0 skips
+Coverage report generated for Unit Tests.
+Line Coverage: 94.12% (80 / 85)
+Branch Coverage: 100.0% (16 / 16)
+```
+
+## 9.5 各言語のモジュール設計比較
+
+| 概念 | Ruby | Java | TypeScript | Python |
+|------|------|------|-----------|--------|
+| モジュール単位 | ファイル（`require_relative`） | パッケージ | ファイル（ES Modules） | パッケージ |
+| 公開制御 | `private` / `protected` / `public` | `public` / package-private | `export` / non-export | `__all__` / `_` 規約 |
+| バレルファイル | `require_relative` 集約 | パッケージの public class | `index.ts` の re-export | `__init__.py` |
+| 名前空間 | モジュール / クラス | パッケージ名 | ファイルパス | モジュールパス |
+| Mix-in | `include` / `extend` | なし（interface） | なし（mixin パターン） | 多重継承 |
+
+## 9.6 まとめ
+
+第 3 部（章 7〜9）を通じて、手続き的な FizzBuzz を OOP 設計に進化させました。
+
+| 章 | テーマ | 適用したパターン |
+|---|--------|---------------|
+| 7 | カプセル化とポリモーフィズム | Strategy パターン、ファクトリメソッド |
+| 8 | デザインパターンの適用 | Value Object、First-Class Collection、Command パターン |
+| 9 | SOLID 原則とモジュール設計 | SRP、OCP、DIP、モジュール分割 |
+
+### Before / After
+
+**Before**（第 2 部終了時）:
+
+```
+lib/fizz_buzz.rb (1 ファイル、1 クラス)
+test/fizz_buzz_test.rb (1 ファイル)
+```
+
+**After**（第 3 部終了時）:
+
+```
+lib/fizz_buzz/
+├── domain/model/    (値オブジェクト、コレクション)
+├── domain/type/     (ビジネスルール)
+└── application/     (コマンド)
+
+test/fizz_buzz/
+├── domain/model/    (値・コレクションのテスト)
+├── domain/type/     (タイプのテスト)
+└── application/     (コマンドのテスト)
+```
+
+次の第 4 部では、関数型プログラミングの観点から FizzBuzz を再構成し、高階関数、不変データ、パターンマッチング、ベンチマークを学びます。

package/lib/assets/docs/article/getting-start-tdd/ruby/10-higher-order-functions-and-composition.md

@@ -0,0 +1,175 @@
+# 第 10 章: 高階関数と関数合成
+
+## 10.1 はじめに
+
+第 3 部ではオブジェクト指向設計により FizzBuzz を構造化しました。この第 4 部では、Ruby の関数型プログラミング機能を使ってコードをさらに柔軟にします。
+
+Ruby はオブジェクト指向言語ですが、**ブロック**・**Proc**・**Lambda** という強力な関数型プリミティブを備えています。本章ではこれらを使って FizzBuzz に高階関数と関数合成を導入します。
+
+## 10.2 ブロック・Proc・Lambda
+
+### ブロック
+
+Ruby のブロックは `{}` または `do...end` で記述する無名のコードブロックです。
+
+```ruby
+# ブロックの基本
+[1, 2, 3].each { |n| puts n }
+
+# do...end 形式
+[1, 2, 3].each do |n|
+  puts n
+end
+```
+
+### Proc
+
+ブロックをオブジェクトとして扱うには `Proc` を使います。
+
+```ruby
+square = Proc.new { |n| n * n }
+square.call(5)  # => 25
+
+# Proc は引数の数が合わなくてもエラーにならない
+square.call(5, 10)  # => 25（余分な引数を無視）
+```
+
+### Lambda
+
+`Lambda` は厳密な Proc です。引数の数をチェックし、`return` の挙動も異なります。
+
+```ruby
+square = ->(n) { n * n }
+square.call(5)  # => 25
+
+# Lambda は引数の数が合わないとエラー
+# square.call(5, 10)  # => ArgumentError
+```
+
+### 比較
+
+| 特徴 | ブロック | Proc | Lambda |
+|------|---------|------|--------|
+| オブジェクト | No | Yes | Yes |
+| 引数チェック | なし | 緩い | 厳密 |
+| return の挙動 | 呼び出し元から返る | 呼び出し元から返る | Lambda 内から返る |
+| 生成方法 | `{}` / `do...end` | `Proc.new {}` | `->() {}` |
+
+## 10.3 FizzBuzzList への関数型メソッド追加
+
+### 問題: Enumerable の返り値
+
+`FizzBuzzList` は `Enumerable` を include しているため、`select` や `map` が使えますが、戻り値は `Array` になります。メソッドチェーンで `FizzBuzzList` を維持するには、専用メソッドが必要です。
+
+### 解決: FizzBuzzList を返すメソッド
+
+```ruby
+class FizzBuzzList
+  # 条件に合う要素だけの FizzBuzzList を返す
+  def select_type(&)
+    FizzBuzzList.new(@value.select(&))
+  end
+
+  # 条件に合わない要素だけの FizzBuzzList を返す
+  def reject_type(&)
+    FizzBuzzList.new(@value.reject(&))
+  end
+
+  # 変換結果の FizzBuzzList を返す
+  def map_type(&)
+    FizzBuzzList.new(@value.map(&))
+  end
+end
+```
+
+Ruby 3.x では `&` だけでブロック引数を転送できます（anonymous block forwarding）。
+
+### テスト
+
+```ruby
+class FizzBuzzListTest < Minitest::Test
+  def test_select_typeでFizzBuzzListを返す
+    type = FizzBuzzType.create(FizzBuzzType::TYPE_01)
+    command = FizzBuzzListCommand.new(type, 15)
+    list = command.execute
+    result = list.select_type { |v| v.value == 'Fizz' }
+    assert_instance_of FizzBuzzList, result
+    assert_equal 4, result.size  # 3,6,9,12（15はFizzBuzz）
+  end
+
+  def test_reject_typeでFizzBuzzListを返す
+    type = FizzBuzzType.create(FizzBuzzType::TYPE_01)
+    command = FizzBuzzListCommand.new(type, 15)
+    list = command.execute
+    result = list.reject_type { |v| v.value == 'Fizz' }
+    assert_instance_of FizzBuzzList, result
+    assert_equal 11, result.size
+  end
+end
+```
+
+## 10.4 述語関数と関数合成
+
+### 述語 Lambda
+
+条件を Lambda として定義すると再利用可能になります。
+
+```ruby
+is_fizz = ->(v) { v.value == 'Fizz' }
+is_buzz = ->(v) { v.value == 'Buzz' }
+is_fizz_buzz = ->(v) { v.value == 'FizzBuzz' }
+
+# 使用例
+list.select_type(&is_fizz)
+list.select_type(&is_buzz)
+```
+
+### 関数合成（`>>` と `<<`）
+
+Ruby 2.6 以降、Proc/Lambda に `>>` と `<<` 演算子で関数合成ができます。
+
+```ruby
+# >> は左から右へ合成（pipe）
+double = ->(n) { n * 2 }
+add_one = ->(n) { n + 1 }
+
+double_then_add = double >> add_one
+double_then_add.call(5)  # => 11（5*2=10, 10+1=11）
+
+# << は右から左へ合成（compose）
+add_then_double = double << add_one
+add_then_double.call(5)  # => 12（5+1=6, 6*2=12）
+```
+
+### カリー化
+
+```ruby
+# カリー化で部分適用
+multiply = ->(a, b) { a * b }
+double = multiply.curry.(2)  # a=2 で部分適用
+double.call(5)  # => 10
+
+triple = multiply.curry.(3)  # a=3 で部分適用
+triple.call(5)  # => 15
+```
+
+## 10.5 各言語の高階関数比較
+
+| 概念 | Ruby | Java | TypeScript | Python |
+|------|------|------|-----------|--------|
+| 無名関数 | `->() {}` / ブロック | Lambda 式 | アロー関数 | `lambda` |
+| 高階関数 | `map` / `select` / `inject` | `Stream` API | `map` / `filter` / `reduce` | `map()` / `filter()` / `reduce()` |
+| 関数合成 | `>>` / `<<` | `Function.compose()` / `andThen()` | カスタム `compose`/`pipe` | `functools.reduce` |
+| カリー化 | `.curry` | 手動実装 | 手動実装 | `functools.partial` |
+| 部分適用 | `.curry.(arg)` | 手動クロージャ | 手動クロージャ | `functools.partial` |
+
+## 10.6 まとめ
+
+この章で学んだこと:
+
+1. **ブロック・Proc・Lambda**: Ruby の 3 つの関数型プリミティブの違いと使い分け
+2. **FizzBuzzList の関数型メソッド**: `select_type`、`reject_type`、`map_type` で FizzBuzzList を返すメソッドチェーン
+3. **述語 Lambda**: 条件を Lambda として定義し再利用
+4. **関数合成**: `>>` / `<<` 演算子による合成とカリー化
+
+次の章では、不変データとパイプライン処理を学びます。

package/lib/assets/docs/article/getting-start-tdd/ruby/11-immutable-data-and-pipeline.md

@@ -0,0 +1,233 @@
+# 第 11 章: 不変データとパイプライン処理
+
+## 11.1 はじめに
+
+前章では高階関数と関数合成を学びました。この章では、**不変データ** の原則と **パイプライン処理** のテクニックを適用して、FizzBuzz のデータ処理をより宣言的にします。
+
+## 11.2 不変データの原則
+
+### freeze による不変性
+
+Ruby の `freeze` メソッドはオブジェクトの変更を禁止します。FizzBuzzList では既にこの原則を適用しています。
+
+```ruby
+class FizzBuzzList
+  def initialize(list = [])
+    @value = list.dup.freeze  # 配列を複製して凍結
+  end
+end
+```
+
+`dup.freeze` のパターンにより:
+- `dup` で元の配列を変更しない
+- `freeze` で内部配列の変更を禁止
+
+### frozen_string_literal
+
+Ruby では `# frozen_string_literal: true` マジックコメントにより、ファイル内のすべての文字列リテラルが自動的に凍結されます。
+
+```ruby
+# frozen_string_literal: true
+
+str = "hello"
+str << " world"  # => FrozenError
+```
+
+### FizzBuzzValue の不変性
+
+`FizzBuzzValue` は `attr_reader` のみ（setter なし）で不変性を実現しています。
+
+```ruby
+class FizzBuzzValue
+  attr_reader :value, :number  # getter のみ
+
+  def initialize(value, number)
+    @value = value
+    @number = number
+  end
+  # setter メソッドは定義しない
+end
+```
+
+## 11.3 パイプライン処理メソッド
+
+### group_by_value
+
+値ごとにグループ化します。
+
+```ruby
+class FizzBuzzList
+  def group_by_value
+    @value.group_by(&:value)
+  end
+end
+```
+
+```ruby
+# 使用例
+type = FizzBuzzType.create(FizzBuzzType::TYPE_01)
+command = FizzBuzzListCommand.new(type, 15)
+list = command.execute
+result = list.group_by_value
+# => { "1" => [FizzBuzzValue(1,1)],
+#      "2" => [FizzBuzzValue(2,2)],
+#      "Fizz" => [FizzBuzzValue(Fizz,3), ...],
+#      ... }
+```
+
+### tally_by_value
+
+値ごとの件数を集計します。Ruby の `tally` メソッドを活用します。
+
+```ruby
+class FizzBuzzList
+  def tally_by_value
+    @value.map(&:value).tally
+  end
+end
+```
+
+```ruby
+# 使用例
+result = list.tally_by_value
+# => { "1" => 1, "2" => 1, "Fizz" => 4, "4" => 1, "Buzz" => 2, ... "FizzBuzz" => 1 }
+```
+
+### take_values / join_values
+
+```ruby
+class FizzBuzzList
+  def take_values(count)
+    FizzBuzzList.new(@value.take(count))
+  end
+
+  def join_values(separator = ', ')
+    @value.join(separator)
+  end
+end
+```
+
+### テスト
+
+```ruby
+class FizzBuzzListTest < Minitest::Test
+  def test_take_valuesで先頭N件を返す
+    type = FizzBuzzType.create(FizzBuzzType::TYPE_01)
+    command = FizzBuzzListCommand.new(type, 15)
+    list = command.execute
+    result = list.take_values(3)
+    assert_instance_of FizzBuzzList, result
+    assert_equal 3, result.size
+  end
+
+  def test_group_by_valueで値ごとにグループ化
+    type = FizzBuzzType.create(FizzBuzzType::TYPE_01)
+    command = FizzBuzzListCommand.new(type, 15)
+    list = command.execute
+    result = list.group_by_value
+    assert_instance_of Hash, result
+    assert result.key?('Fizz')
+    assert result.key?('Buzz')
+    assert result.key?('FizzBuzz')
+  end
+
+  def test_tally_by_valueで値ごとの件数を返す
+    type = FizzBuzzType.create(FizzBuzzType::TYPE_01)
+    command = FizzBuzzListCommand.new(type, 15)
+    list = command.execute
+    result = list.tally_by_value
+    assert_equal 1, result['FizzBuzz']
+    assert_equal 4, result['Fizz']
+    assert_equal 2, result['Buzz']
+  end
+
+  def test_join_valuesで文字列結合
+    values = [
+      FizzBuzzValue.new('1', 1),
+      FizzBuzzValue.new('2', 2),
+      FizzBuzzValue.new('Fizz', 3)
+    ]
+    list = FizzBuzzList.new(values)
+    assert_equal '1, 2, Fizz', list.join_values
+  end
+end
+```
+
+## 11.4 then によるパイプライン
+
+Ruby 2.6 以降、`then`（または `yield_self`）でパイプライン処理が書けます。
+
+### FizzBuzzListCommand のリファクタリング
+
+```ruby
+class FizzBuzzListCommand
+  def execute
+    (1..@count)
+      .map { |number| @type.generate(number) }
+      .then { |list| FizzBuzzList.new(list) }
+  end
+end
+```
+
+`then` を使うことで、処理の流れが上から下へ自然に読めます:
+1. `(1..@count)` — 1 から count の Range を作成
+2. `.map { ... }` — 各数値を FizzBuzzValue に変換
+3. `.then { ... }` — 結果の配列を FizzBuzzList でラップ
+
+### メソッドチェーンの活用
+
+```ruby
+# パイプライン処理の例
+type = FizzBuzzType.create(FizzBuzzType::TYPE_01)
+command = FizzBuzzListCommand.new(type, 100)
+result = command.execute
+  .select_type { |v| v.value == 'Fizz' }
+  .take_values(5)
+  .join_values(', ')
+# => "Fizz, Fizz, Fizz, Fizz, Fizz"
+```
+
+## 11.5 Lazy Enumerator
+
+Ruby の `lazy` メソッドで遅延評価が可能です。大量データの処理で効率的です。
+
+```ruby
+# 遅延評価によるフィルタリング
+(1..Float::INFINITY)
+  .lazy
+  .select { |n| (n % 3).zero? }
+  .first(5)
+# => [3, 6, 9, 12, 15]
+
+# FizzBuzz への適用例
+type = FizzBuzzType.create(FizzBuzzType::TYPE_01)
+(1..Float::INFINITY)
+  .lazy
+  .map { |n| type.generate(n) }
+  .select { |v| v.value == 'FizzBuzz' }
+  .first(3)
+  .map(&:number)
+# => [15, 30, 45]
+```
+
+## 11.6 各言語のパイプライン比較
+
+| 概念 | Ruby | Java | TypeScript | Python |
+|------|------|------|-----------|--------|
+| パイプライン | `then` / メソッドチェーン | Stream API | メソッドチェーン | ジェネレータ |
+| グルーピング | `group_by` | `Collectors.groupingBy` | カスタム `groupBy` | `itertools.groupby` |
+| 集計 | `tally` | `Collectors.counting` | カスタム `countBy` | `Counter` |
+| 結合 | `join` | `Collectors.joining` | `join` | `str.join` |
+| 遅延評価 | `lazy` | `Stream`（デフォルト遅延） | ジェネレータ `function*` | ジェネレータ |
+| 不変性 | `freeze` / `dup.freeze` | `final` / `unmodifiableList` | `Object.freeze` / `readonly` | `tuple` / `frozenset` |
+
+## 11.7 まとめ
+
+この章で学んだこと:
+
+1. **不変データ**: `freeze`、`dup.freeze`、`frozen_string_literal` による不変性の確保
+2. **パイプラインメソッド**: `group_by_value`、`tally_by_value`、`take_values`、`join_values`
+3. **then パイプライン**: `then` を使った宣言的な処理の流れ
+4. **Lazy Enumerator**: 遅延評価による無限シーケンスの効率的な処理
+
+次の章では、パターンマッチングによるエラーハンドリングとベンチマークを学びます。