@k2works/claude-code-booster 2.7.1 → 3.1.0

package/lib/assets/docs/article/functional-desgin-ppp/elixir/05-property-based-testing.md

@@ -0,0 +1,268 @@
+# Chapter 05: プロパティベーステスト
+
+Elixir における StreamData を使ったプロパティベーステストについて学びます。
+
+## 概要
+
+従来の例示ベーステストでは、特定の入力に対する期待される出力を手動で指定します。
+プロパティベーステストでは、**すべての入力に対して成り立つべき性質（プロパティ）**を
+定義し、ランダムに生成された多数の入力でその性質を検証します。
+
+## 主なトピック
+
+1. **ジェネレータの基本**
+2. **プロパティの定義**
+3. **収縮（シュリンキング）**
+4. **カスタムジェネレータ**
+5. **ドメイン固有のプロパティ**
+
+## StreamData ライブラリ
+
+Elixir でプロパティベーステストを行うには、`stream_data` ライブラリを使用します。
+
+```elixir
+# mix.exs
+defp deps do
+  [
+    {:stream_data, "~> 1.0", only: :test}
+  ]
+end
+```
+
+## プロパティの種類
+
+### 冪等性（Idempotency）
+
+同じ操作を複数回適用しても結果が変わらない性質。
+
+```elixir
+property "sort は冪等" do
+  check all list <- list_of(integer()) do
+    assert Enum.sort(Enum.sort(list)) == Enum.sort(list)
+  end
+end
+```
+
+### ラウンドトリップ（Round-trip）
+
+エンコード・デコードで元の値に戻る性質。
+
+```elixir
+property "encode/decode はラウンドトリップ" do
+  check all n <- integer() do
+    encoded = encode(n)
+    {:ok, decoded} = decode(encoded)
+    assert decoded == n
+  end
+end
+```
+
+### 不変条件（Invariant）
+
+操作の前後で保存される性質。
+
+```elixir
+property "reverse は長さを保存する" do
+  check all list <- list_of(term()) do
+    assert length(Enum.reverse(list)) == length(list)
+  end
+end
+```
+
+### 反転（Inverse）
+
+ある操作とその逆操作。
+
+```elixir
+property "reverse の reverse は元に戻る" do
+  check all list <- list_of(integer()) do
+    assert Enum.reverse(Enum.reverse(list)) == list
+  end
+end
+```
+
+## 基本的なジェネレータ
+
+```elixir
+use ExUnitProperties
+
+# 整数
+integer()           # 任意の整数
+positive_integer()  # 正の整数
+non_negative_integer()  # 0 以上の整数
+integer(1..100)     # 範囲付き整数
+
+# 文字列
+string(:alphanumeric)
+string(:printable, min_length: 1, max_length: 10)
+
+# リスト
+list_of(integer())
+list_of(integer(), min_length: 1, max_length: 5)
+
+# マップ
+map_of(atom(:alphanumeric), integer())
+
+# その他
+boolean()
+binary()
+term()
+member_of(["a", "b", "c"])
+```
+
+## カスタムジェネレータ
+
+```elixir
+# メールアドレスのカスタムジェネレータ
+defp email_generator do
+  gen all local <- string(:alphanumeric, min_length: 1, max_length: 10),
+          domain <- string(:alphanumeric, min_length: 1, max_length: 10),
+          tld <- member_of(["com", "org", "net", "io"]) do
+    "#{local}@#{domain}.#{tld}"
+  end
+end
+
+property "生成されたメールは有効" do
+  check all email <- email_generator() do
+    assert String.contains?(email, "@")
+    assert String.contains?(email, ".")
+  end
+end
+```
+
+## 実装例
+
+### 数学関数のプロパティ
+
+```elixir
+defmodule Chapter05 do
+  @doc """
+  絶対値を返す。
+  
+  ## プロパティ
+  - 結果は常に非負
+  - 冪等性: abs(abs(x)) == abs(x)
+  - 偶関数: abs(-x) == abs(x)
+  """
+  def absolute(n) when n < 0, do: -n
+  def absolute(n), do: n
+end
+```
+
+```elixir
+describe "absolute/1 のプロパティ" do
+  property "結果は常に非負" do
+    check all n <- integer() do
+      assert Chapter05.absolute(n) >= 0
+    end
+  end
+
+  property "冪等性" do
+    check all n <- integer() do
+      assert Chapter05.absolute(Chapter05.absolute(n)) == Chapter05.absolute(n)
+    end
+  end
+
+  property "偶関数" do
+    check all n <- integer() do
+      assert Chapter05.absolute(-n) == Chapter05.absolute(n)
+    end
+  end
+end
+```
+
+### ドメインモデルのプロパティ
+
+```elixir
+defmodule Money do
+  defstruct [:amount, :currency]
+
+  def new(amount, currency), do: %__MODULE__{amount: amount, currency: currency}
+  
+  def add(%{currency: c} = m1, %{currency: c} = m2) do
+    {:ok, new(m1.amount + m2.amount, c)}
+  end
+  def add(_, _), do: {:error, "Currency mismatch"}
+  
+  def zero(currency), do: new(0, currency)
+end
+```
+
+```elixir
+describe "Money のモノイド則" do
+  defp money_generator(currency) do
+    gen all amount <- integer() do
+      Money.new(amount, currency)
+    end
+  end
+
+  property "結合律" do
+    check all a <- money_generator("JPY"),
+              b <- money_generator("JPY"),
+              c <- money_generator("JPY") do
+      {:ok, ab} = Money.add(a, b)
+      {:ok, ab_c} = Money.add(ab, c)
+      {:ok, bc} = Money.add(b, c)
+      {:ok, a_bc} = Money.add(a, bc)
+      assert ab_c == a_bc
+    end
+  end
+
+  property "単位元" do
+    check all m <- money_generator("JPY") do
+      zero = Money.zero("JPY")
+      {:ok, result} = Money.add(m, zero)
+      assert result == m
+    end
+  end
+
+  property "可換律" do
+    check all a <- money_generator("JPY"),
+              b <- money_generator("JPY") do
+      {:ok, ab} = Money.add(a, b)
+      {:ok, ba} = Money.add(b, a)
+      assert ab == ba
+    end
+  end
+end
+```
+
+## 収縮（シュリンキング）
+
+テストが失敗した場合、StreamData は失敗を引き起こす最小の入力を見つけようとします。
+
+```elixir
+# 故意に失敗するテスト（デモ用）
+property "リストの合計は100未満" do
+  check all list <- list_of(positive_integer(), min_length: 1) do
+    assert Enum.sum(list) < 100
+  end
+end
+
+# 出力例:
+# Failed with generated values (after 5 successful runs):
+#     * list <- [100]
+# 
+# 収縮により、最小の反例 [100] が見つかる
+```
+
+## テストのベストプラクティス
+
+1. **明確なプロパティを定義する** - 何を検証するか明確に
+2. **ジェネレータを適切に制約する** - 無効な入力を生成しない
+3. **カスタムジェネレータを活用する** - ドメイン固有の値を生成
+4. **収縮を理解する** - 最小の反例を活用
+5. **例示テストと併用する** - 両方のアプローチを使う
+
+## まとめ
+
+- **プロパティベーステスト**で多くのケースを自動検証
+- **StreamData**で Elixir のプロパティテストを実現
+- **カスタムジェネレータ**でドメイン固有のテストデータを生成
+- **収縮**で最小の失敗ケースを特定
+- **例示テストと併用**で堅牢なテストスイートを構築
+
+## 関連リソース
+
+- [StreamData ドキュメント](https://hexdocs.pm/stream_data/)
+- [Property-based testing with PropEr, Erlang, and Elixir](https://pragprog.com/titles/fhproper/property-based-testing-with-proper-erlang-and-elixir/)

package/lib/assets/docs/article/functional-desgin-ppp/elixir/06-tdd-and-fp.md

@@ -0,0 +1,294 @@
+# Chapter 06: TDD と関数型プログラミング
+
+Elixir におけるテスト駆動開発（TDD）と関数型プログラミングの融合について学びます。
+
+## 概要
+
+テスト駆動開発（TDD）は、テストを先に書いてから実装するソフトウェア開発手法です。
+関数型プログラミングの純粋関数と不変データは、TDD と非常に相性が良いです。
+
+## 主なトピック
+
+1. **TDD の基本サイクル（Red-Green-Refactor）**
+2. **テスタブルな設計**
+3. **純粋関数とテスト容易性**
+4. **モックとスタブの代替手法**
+5. **Outside-In TDD**
+6. **Parameterized Tests**
+
+## TDD の基本サイクル
+
+### Red-Green-Refactor
+
+1. **Red**: 失敗するテストを書く
+2. **Green**: テストを通す最小限の実装
+3. **Refactor**: コードを整理（テストは通ったまま）
+
+### FizzBuzz の例
+
+```elixir
+# Step 1: Red - 失敗するテストを書く
+test "通常の数値は文字列として返す" do
+  assert FizzBuzz.convert(1) == "1"
+end
+
+# Step 2: Green - 最小限の実装
+def convert(n), do: Integer.to_string(n)
+
+# Step 3: 次のテストを追加
+test "3の倍数は 'Fizz' を返す" do
+  assert FizzBuzz.convert(3) == "Fizz"
+end
+
+# 実装を拡張
+def convert(n) when rem(n, 3) == 0, do: "Fizz"
+def convert(n), do: Integer.to_string(n)
+
+# 以下同様に 5の倍数、15の倍数を追加...
+```
+
+## テスタブルな設計
+
+### 依存性の注入
+
+外部依存を関数として注入することで、テスト時にスタブを使用できます。
+
+```elixir
+defmodule PricingService do
+  @doc """
+  割引率を取得する関数を注入することで、
+  外部サービスをモック可能にする。
+  """
+  def calculate_price(product_id, base_price, discount_fetcher) do
+    discount = discount_fetcher.(product_id)
+    base_price * (1.0 - discount)
+  end
+end
+
+# テストでの使用
+test "割引率を適用して価格を計算する" do
+  # スタブ：常に10%割引を返す
+  discount_fetcher = fn _product_id -> 0.10 end
+  
+  assert PricingService.calculate_price("PROD001", 1000, discount_fetcher) == 900.0
+end
+
+# 本番での使用
+def production_discount_fetcher(product_id) do
+  DiscountAPI.fetch(product_id)
+end
+
+PricingService.calculate_price("PROD001", 1000, &production_discount_fetcher/1)
+```
+
+## 純粋関数によるビジネスロジック
+
+ビジネスロジックを純粋関数として実装することで、テストが容易になります。
+
+```elixir
+defmodule OrderProcessor do
+  @doc "注文の小計を計算する（純粋関数）"
+  def calculate_subtotal(items) do
+    items
+    |> Enum.map(fn {_name, qty, price} -> qty * price end)
+    |> Enum.sum()
+  end
+
+  @doc "顧客タイプに応じた割引率を返す（純粋関数）"
+  def discount_rate(:regular), do: 0.0
+  def discount_rate(:premium), do: 0.05
+  def discount_rate(:vip), do: 0.10
+
+  @doc "税額を計算する（純粋関数）"
+  def calculate_tax(amount, tax_rate), do: amount * tax_rate
+
+  @doc "注文を処理する（純粋関数の組み合わせ）"
+  def process_order(%{items: items, customer_type: customer_type}, tax_rate) do
+    subtotal = calculate_subtotal(items)
+    discount_amount = subtotal * discount_rate(customer_type)
+    discounted = subtotal - discount_amount
+    tax_amount = calculate_tax(discounted, tax_rate)
+    total = discounted + tax_amount
+
+    %{
+      subtotal: subtotal,
+      discount: discount_amount,
+      tax: tax_amount,
+      total: total
+    }
+  end
+end
+```
+
+テストは各純粋関数を独立してテストできます。
+
+```elixir
+describe "OrderProcessor" do
+  test "calculate_subtotal" do
+    items = [{"Item1", 2, 100.0}, {"Item2", 3, 50.0}]
+    assert OrderProcessor.calculate_subtotal(items) == 350.0
+  end
+
+  test "discount_rate" do
+    assert OrderProcessor.discount_rate(:regular) == 0.0
+    assert OrderProcessor.discount_rate(:premium) == 0.05
+    assert OrderProcessor.discount_rate(:vip) == 0.10
+  end
+
+  test "process_order for VIP customer" do
+    order = %{items: [{"Item", 1, 1000.0}], customer_type: :vip}
+    result = OrderProcessor.process_order(order, 0.10)
+    
+    assert result.subtotal == 1000.0
+    assert result.discount == 100.0
+    assert result.tax == 90.0
+    assert result.total == 990.0
+  end
+end
+```
+
+## 状態遷移のテスト
+
+状態遷移を純粋関数としてモデル化します。
+
+```elixir
+defmodule OrderState do
+  def new(id, items) do
+    %{id: id, state: :pending, items: items, history: [:pending]}
+  end
+
+  def confirm(%{state: :pending} = order) do
+    {:ok, %{order | state: :confirmed, history: [:confirmed | order.history]}}
+  end
+  def confirm(_), do: {:error, "Cannot confirm"}
+
+  def ship(%{state: :confirmed} = order) do
+    {:ok, %{order | state: :shipped, history: [:shipped | order.history]}}
+  end
+  def ship(_), do: {:error, "Cannot ship"}
+  
+  # ... 他の遷移
+end
+```
+
+```elixir
+describe "OrderState 状態遷移" do
+  test "正常な状態遷移" do
+    order = OrderState.new("ORD001", [])
+    
+    {:ok, order} = OrderState.confirm(order)
+    assert order.state == :confirmed
+    
+    {:ok, order} = OrderState.ship(order)
+    assert order.state == :shipped
+  end
+
+  test "不正な状態遷移はエラー" do
+    order = OrderState.new("ORD001", [])
+    # pending から直接 ship はできない
+    assert {:error, _} = OrderState.ship(order)
+  end
+end
+```
+
+## テストデータビルダーパターン
+
+テストデータを柔軟に構築するパターンです。
+
+```elixir
+defmodule UserBuilder do
+  def build do
+    %{
+      name: "Test User",
+      email: "test@example.com",
+      age: 25,
+      role: :user,
+      active: true
+    }
+  end
+
+  def build(overrides) do
+    build() |> Map.merge(Map.new(overrides))
+  end
+
+  def admin, do: build(role: :admin)
+  def inactive, do: build(active: false)
+
+  def build_list(count) do
+    Enum.map(1..count, fn i ->
+      build(name: "User #{i}", email: "user#{i}@example.com")
+    end)
+  end
+end
+```
+
+```elixir
+test "管理者のみがアクセス可能" do
+  admin = UserBuilder.admin()
+  user = UserBuilder.build()
+  
+  assert authorize(admin, :admin_panel) == :ok
+  assert authorize(user, :admin_panel) == :error
+end
+```
+
+## パラメタライズドテスト
+
+同じテストロジックを複数の入力で実行します。
+
+```elixir
+describe "FizzBuzz パラメタライズドテスト" do
+  for {input, expected} <- [
+    {1, "1"},
+    {2, "2"},
+    {3, "Fizz"},
+    {5, "Buzz"},
+    {15, "FizzBuzz"}
+  ] do
+    test "FizzBuzz.convert(#{input}) == #{expected}" do
+      assert FizzBuzz.convert(unquote(input)) == unquote(expected)
+    end
+  end
+end
+```
+
+## Result 型を使ったエラーハンドリング
+
+```elixir
+defmodule Calculator do
+  def divide(_, b) when b == 0 or b == 0.0 do
+    {:error, "Division by zero"}
+  end
+  def divide(a, b), do: {:ok, a / b}
+
+  def chain(n), do: {:ok, n}
+
+  def then_divide({:ok, a}, b), do: divide(a, b)
+  def then_divide(error, _), do: error
+end
+```
+
+```elixir
+test "エラーはチェインを通じて伝播する" do
+  result =
+    Calculator.chain(10)
+    |> Calculator.then_divide(0)
+    |> Calculator.then_add(5)
+
+  assert {:error, "Division by zero"} = result
+end
+```
+
+## まとめ
+
+- **TDD サイクル**（Red-Green-Refactor）で段階的に実装
+- **依存性注入**でテスタブルな設計
+- **純粋関数**でビジネスロジックを表現
+- **状態遷移**を純粋関数としてモデル化
+- **テストデータビルダー**で柔軟なテストデータ作成
+- **パラメタライズドテスト**で多くのケースをカバー
+
+## 関連リソース
+
+- [ExUnit ドキュメント](https://hexdocs.pm/ex_unit/)
+- [Test-Driven Development by Example](https://www.amazon.com/Test-Driven-Development-Kent-Beck/dp/0321146530)

package/lib/assets/docs/article/functional-desgin-ppp/elixir/07-effects-and-pure-functions.md

@@ -0,0 +1,164 @@
+# Chapter 07: 副作用と純粋関数
+
+Elixir における副作用の管理と純粋関数の分離について学びます。
+
+## 概要
+
+関数型プログラミングでは、副作用（I/O、状態変更、時間、乱数）を純粋なビジネスロジックから分離することが重要です。このチャプターでは、その設計パターンを紹介します。
+
+## 主なトピック
+
+1. **純粋関数と副作用の分離**
+2. **Functional Core, Imperative Shell**
+3. **副作用の遅延実行**
+4. **Reader パターン**
+5. **依存性注入**
+
+## 純粋関数 vs 副作用
+
+### 純粋関数
+
+- 同じ入力に対して常に同じ出力
+- 外部状態を変更しない
+
+```elixir
+# 純粋関数の例
+def add(a, b), do: a + b
+def upcase(s), do: String.upcase(s)
+```
+
+### 副作用を持つ関数
+
+- I/O（コンソール、ファイル、ネットワーク）
+- 状態変更
+- 現在時刻の取得
+- 乱数生成
+
+```elixir
+# 副作用を持つ関数
+def current_time, do: DateTime.utc_now()  # 非決定的
+def random_number, do: :rand.uniform()    # 非決定的
+def print(msg), do: IO.puts(msg)          # I/O
+```
+
+## Functional Core, Imperative Shell
+
+ビジネスロジックを純粋関数として実装し、副作用は境界層で処理します。
+
+```elixir
+# Functional Core（純粋関数）
+defmodule PricingCore do
+  def apply_discount(price, %{type: :percentage, value: pct}) do
+    price * (1 - pct / 100)
+  end
+
+  def calculate_total(products) do
+    products |> Enum.map(& &1.price) |> Enum.sum()
+  end
+end
+
+# Imperative Shell（副作用を扱う）
+defmodule PricingShell do
+  def calculate_order_price(products, discount_fetcher, discount_code, tax_rate) do
+    # 副作用：外部から割引情報を取得
+    discount = discount_fetcher.(discount_code)
+    # 純粋関数でビジネスロジックを実行
+    PricingCore.calculate_final_price(products, discount, tax_rate)
+  end
+end
+```
+
+## 副作用の遅延実行（Effect as Data）
+
+副作用をデータとして表現し、実行を遅延させます。
+
+```elixir
+defmodule Effect do
+  def console_log(message) do
+    {:effect, :console_log, message, fn _ -> :ok end}
+  end
+
+  def get_current_time do
+    {:effect, :get_time, nil, fn time -> time end}
+  end
+
+  # 本番用インタープリター
+  def run({:effect, :console_log, message, cont}) do
+    IO.puts(message)
+    cont.(:ok)
+  end
+
+  # テスト用インタープリター
+  def run_test({:effect, effect_type, _, cont}, mock_values) do
+    cont.(Map.get(mock_values, effect_type))
+  end
+end
+```
+
+## Reader パターン
+
+環境（設定、依存性）を引数として渡す関数をラップします。
+
+```elixir
+defmodule Reader do
+  def pure(value), do: fn _env -> value end
+  def ask, do: fn env -> env end
+  def asks(selector), do: fn env -> selector.(env) end
+
+  def flat_map(reader, f) do
+    fn env -> f.(reader.(env)).(env) end
+  end
+
+  def run(reader, env), do: reader.(env)
+end
+
+# 使用例
+def get_db_url do
+  Reader.asks(fn config -> config.db_url end)
+end
+
+def build_service do
+  Reader.flat_map(get_db_url(), fn db_url ->
+    Reader.flat_map(get_api_key(), fn api_key ->
+      Reader.pure(%{db: db_url, key: api_key, ready: true})
+    end)
+  end)
+end
+```
+
+## 時間の抽象化
+
+時間依存をテスト可能にします。
+
+```elixir
+defmodule TimeService do
+  def add_timestamp(data, time_provider) do
+    Map.put(data, :timestamp, time_provider.())
+  end
+
+  def is_expired?(expiry_date, time_provider) do
+    DateTime.compare(time_provider.(), expiry_date) == :gt
+  end
+end
+
+# テスト
+test "is_expired? は期限切れを判定する" do
+  now = ~U[2024-01-15 12:00:00Z]
+  provider = fn -> now end
+
+  assert TimeService.is_expired?(~U[2024-01-10 12:00:00Z], provider) == true
+  assert TimeService.is_expired?(~U[2024-01-20 12:00:00Z], provider) == false
+end
+```
+
+## まとめ
+
+- **純粋関数**でビジネスロジックを実装
+- **Functional Core, Imperative Shell**で副作用を分離
+- **依存性注入**でテスト可能な設計
+- **Reader パターン**で環境を引き回す
+
+## 関連リソース
+
+- [Boundaries by Gary Bernhardt](https://www.destroyallsoftware.com/talks/boundaries)
+- [Functional Core, Imperative Shell](https://www.youtube.com/watch?v=yTkzNHF6rMs)