@k2works/claude-code-booster 3.0.0 → 3.1.0

package/lib/assets/docs/article/getting-start-tdd/elixir/11-stream-and-lazy-evaluation.md

@@ -0,0 +1,142 @@
+# 第 11 章: Stream と遅延評価
+
+## 11.1 はじめに
+
+この章では、`Stream` モジュールを使った遅延評価を学びます。`Enum` による先行評価との違いを理解し、FizzBuzz の無限ストリームを安全に扱う方法を確認します。
+
+## 11.2 Stream.iterate / Stream.map / Stream.take の基本
+
+`Stream` は遅延評価です。`Enum` のようにすぐ計算せず、必要になったときにだけ処理します。
+
+```elixir
+defmodule FizzBuzz.Streaming do
+  def generate(number) when rem(number, 15) == 0, do: "FizzBuzz"
+  def generate(number) when rem(number, 3) == 0, do: "Fizz"
+  def generate(number) when rem(number, 5) == 0, do: "Buzz"
+  def generate(number), do: Integer.to_string(number)
+
+  def lazy_stream do
+    Stream.iterate(1, &(&1 + 1))
+    |> Stream.map(&generate/1)
+  end
+end
+```
+
+`lazy_stream/0` は無限列ですが、実際にはまだ計算されていません。
+
+## 11.3 遅延評価と先行評価の違い: Enum vs Stream
+
+`Enum` はコレクション全体を順に評価します。`Stream` は最後に `Enum.take` などの消費処理が呼ばれたときだけ評価します。
+
+```elixir
+defmodule FizzBuzz.EagerVsLazy do
+  def eager(limit) do
+    1..limit
+    |> Enum.map(&expensive_generate/1)
+  end
+
+  def lazy(limit) do
+    1..limit
+    |> Stream.map(&expensive_generate/1)
+    |> Enum.take(5)
+  end
+
+  defp expensive_generate(number) do
+    Process.sleep(1)
+
+    cond do
+      rem(number, 15) == 0 -> "FizzBuzz"
+      rem(number, 3) == 0 -> "Fizz"
+      rem(number, 5) == 0 -> "Buzz"
+      true -> Integer.to_string(number)
+    end
+  end
+end
+```
+
+`eager/1` は `limit` 件すべてを計算しますが、`lazy/1` は先頭 5 件だけ計算します。
+
+## 11.4 lazy_stream/0 から必要な分だけ取得する
+
+無限ストリームは必ず `Enum.take/2` や `Enum.at/2` で境界を作って使います。
+
+```elixir
+defmodule FizzBuzz.StreamConsumer do
+  alias FizzBuzz.Streaming
+
+  def first_ten do
+    Streaming.lazy_stream()
+    |> Enum.take(10)
+  end
+
+  def hundredth_value do
+    Streaming.lazy_stream()
+    |> Enum.at(99)
+  end
+end
+```
+
+## 11.5 パフォーマンス比較の考え方
+
+大量データで「一部だけ必要」なケースでは、`Stream` の方が有利です。評価コストの高い関数を使うほど差が出ます。
+
+```elixir
+defmodule FizzBuzz.BenchmarkLike do
+  def compare(limit) do
+    {eager_us, _} =
+      :timer.tc(fn ->
+        1..limit
+        |> Enum.map(&heavy_work/1)
+        |> Enum.take(10)
+      end)
+
+    {lazy_us, _} =
+      :timer.tc(fn ->
+        1..limit
+        |> Stream.map(&heavy_work/1)
+        |> Enum.take(10)
+      end)
+
+    %{eager_us: eager_us, lazy_us: lazy_us}
+  end
+
+  defp heavy_work(n) do
+    if rem(n, 15) == 0, do: "FizzBuzz", else: Integer.to_string(n)
+  end
+end
+```
+
+## 11.6 ExUnit で Stream の挙動を検証する
+
+```elixir
+defmodule FizzBuzz.StreamTest do
+  use ExUnit.Case, async: true
+
+  alias FizzBuzz.{BenchmarkLike, StreamConsumer, Streaming}
+
+  test "lazy_stream/0 から先頭 5 件を取り出せる" do
+    assert Streaming.lazy_stream() |> Enum.take(5) == ["1", "2", "Fizz", "4", "Buzz"]
+  end
+
+  test "Enum.at/2 で任意位置を取得できる" do
+    assert StreamConsumer.hundredth_value() == "Buzz"
+  end
+
+  test "無限ストリームでも take で安全に扱える" do
+    result = Streaming.lazy_stream() |> Enum.take(15)
+    assert Enum.at(result, 14) == "FizzBuzz"
+  end
+
+  test "遅延評価は先頭だけ必要な処理で有利になりやすい" do
+    times = BenchmarkLike.compare(50_000)
+
+    assert is_integer(times.eager_us)
+    assert is_integer(times.lazy_us)
+    assert times.lazy_us <= times.eager_us
+  end
+end
+```
+
+## 11.7 まとめ
+
+この章では、`Stream.iterate`、`Stream.map`、`Stream.take` を使って遅延評価を実現し、`Enum` との違いを確認しました。`lazy_stream/0` のような無限データは、必要な分だけ取り出す設計にすると、安全性と性能を両立できます。

package/lib/assets/docs/article/getting-start-tdd/elixir/12-error-handling-and-with.md

@@ -0,0 +1,145 @@
+# 第 12 章: エラーハンドリングと with 構文
+
+## 12.1 はじめに
+
+この章では、Elixir で例外に頼りすぎず、値としてエラーを扱う方法を学びます。`{:ok, value}` / `{:error, reason}` の Result パターン、`with` 構文による連鎖処理、`try/rescue` との使い分けを整理します。
+
+## 12.2 タグ付きタプルによる Result パターン
+
+関数の成功と失敗を同じ型で返すと、呼び出し側が分岐を明示できます。
+
+```elixir
+defmodule FizzBuzz.Safe do
+  def safe_generate(number) when is_integer(number) and number > 0 do
+    {:ok, generate(number)}
+  end
+
+  def safe_generate(number) when is_integer(number) do
+    {:error, :non_positive}
+  end
+
+  def safe_generate(_), do: {:error, :not_integer}
+
+  defp generate(number) when rem(number, 15) == 0, do: "FizzBuzz"
+  defp generate(number) when rem(number, 3) == 0, do: "Fizz"
+  defp generate(number) when rem(number, 5) == 0, do: "Buzz"
+  defp generate(number), do: Integer.to_string(number)
+end
+```
+
+## 12.3 safe_generate/1 で安全な生成を行う
+
+`safe_generate/1` は例外を投げず、入力エラーを `{:error, reason}` で返します。これにより、関数合成時の失敗経路を追いやすくなります。
+
+```elixir
+defmodule FizzBuzz.SafeFacade do
+  alias FizzBuzz.Safe
+
+  def safe_generate_message(input) do
+    case Safe.safe_generate(input) do
+      {:ok, value} -> "result: #{value}"
+      {:error, reason} -> "error: #{reason}"
+    end
+  end
+end
+```
+
+## 12.4 with 構文でモナド的にエラーを連鎖する
+
+`with` は「途中で `{:error, reason}` が出たら即終了」の流れを簡潔に書けます。`safe_generate_list/1` では、各要素の検証と変換を連鎖します。
+
+```elixir
+defmodule FizzBuzz.SafeList do
+  alias FizzBuzz.Safe
+
+  def safe_generate_list(inputs) when is_list(inputs) do
+    inputs
+    |> Enum.reduce_while({:ok, []}, fn input, {:ok, acc} ->
+      with {:ok, value} <- Safe.safe_generate(input) do
+        {:cont, {:ok, acc ++ [value]}}
+      else
+        {:error, reason} -> {:halt, {:error, {:invalid_item, input, reason}}}
+      end
+    end)
+  end
+
+  def safe_generate_list(_), do: {:error, :not_list}
+end
+```
+
+## 12.5 try/rescue vs with の使い分け
+
+`with` は、想定内エラーをタグ付きタプルで扱うときに使います。`try/rescue` は、外部ライブラリや危険な処理で例外が発生しうるときに限定します。
+
+```elixir
+defmodule FizzBuzz.ExceptionBoundary do
+  alias FizzBuzz.Safe
+
+  def parse_and_generate(text) do
+    with {number, ""} <- Integer.parse(text),
+         {:ok, value} <- Safe.safe_generate(number) do
+      {:ok, value}
+    else
+      :error -> {:error, :parse_error}
+      {:error, reason} -> {:error, reason}
+    end
+  end
+
+  def parse_with_rescue(text) do
+    try do
+      number = String.to_integer(text)
+      Safe.safe_generate(number)
+    rescue
+      ArgumentError -> {:error, :parse_error}
+    end
+  end
+end
+```
+
+## 12.6 関数型エラーハンドリングの設計指針
+
+- ドメイン上で起こりうる失敗は、例外ではなく `{:error, reason}` で表現します。
+- `reason` は機械的に扱える atom や構造化データにします。
+- `with` は 2 段以上の処理連鎖で使い、`case` のネストを減らします。
+- 例外は境界層で捕捉し、内部では Result パターンへ正規化します。
+
+## 12.7 ExUnit でエラーハンドリングを検証する
+
+```elixir
+defmodule FizzBuzz.ErrorHandlingTest do
+  use ExUnit.Case, async: true
+
+  alias FizzBuzz.{ExceptionBoundary, Safe, SafeList}
+
+  test "safe_generate/1 は成功時に {:ok, value} を返す" do
+    assert Safe.safe_generate(15) == {:ok, "FizzBuzz"}
+  end
+
+  test "safe_generate/1 は入力エラーを {:error, reason} で返す" do
+    assert Safe.safe_generate(0) == {:error, :non_positive}
+    assert Safe.safe_generate("3") == {:error, :not_integer}
+  end
+
+  test "safe_generate_list/1 は全要素が正しければ一覧を返す" do
+    assert SafeList.safe_generate_list([1, 3, 5]) == {:ok, ["1", "Fizz", "Buzz"]}
+  end
+
+  test "safe_generate_list/1 は最初の不正要素で停止する" do
+    assert SafeList.safe_generate_list([1, -1, 3]) == {:error, {:invalid_item, -1, :non_positive}}
+  end
+
+  test "with を使った parse_and_generate/1 は parse エラーを返せる" do
+    assert ExceptionBoundary.parse_and_generate("abc") == {:error, :parse_error}
+    assert ExceptionBoundary.parse_and_generate("15") == {:ok, "FizzBuzz"}
+  end
+
+  test "try/rescue ベースの実装も同じ契約に揃えられる" do
+    assert ExceptionBoundary.parse_with_rescue("abc") == {:error, :parse_error}
+    assert ExceptionBoundary.parse_with_rescue("5") == {:ok, "Buzz"}
+  end
+end
+```
+
+## 12.8 まとめ
+
+この章では、`safe_generate/1` と `safe_generate_list/1` を通じて Result パターンと `with` 構文を使ったエラーハンドリングを確認しました。想定内エラーは値で返し、想定外例外は境界で `try/rescue` する設計にすると、関数型らしい見通しのよいコードになります。

package/lib/assets/docs/article/getting-start-tdd/elixir/index.md

@@ -0,0 +1,35 @@
+# テスト駆動開発から始める Elixir 入門
+
+## 概要
+
+FizzBuzz 問題を題材に、Elixir でテスト駆動開発を体験する。
+
+## 対象読者
+
+- プログラミング基礎を持ち、TDD や Elixir に興味がある開発者
+
+## 目次
+
+### 第 1 部: TDD の基本サイクル
+
+1. [01: TODO リストと最初のテスト](./01-todo-list-and-first-test.md)
+2. [02: 仮実装と三角測量](./02-fake-it-and-triangulation.md)
+3. [03: 明白な実装とリファクタリング](./03-obvious-implementation-and-refactoring.md)
+
+### 第 2 部: 開発環境と自動化
+
+1. [04: バージョン管理と Conventional Commits](./04-version-control-and-conventional-commits.md)
+2. [05: パッケージ管理と静的解析](./05-package-management-and-static-analysis.md)
+3. [06: タスクランナーと CI/CD](./06-task-runner-and-ci-cd.md)
+
+### 第 3 部: オブジェクト指向設計
+
+1. [07: 構造体とプロトコルによるポリモーフィズム](./07-structs-and-protocols.md)
+2. [08: パターンマッチとガード節](./08-pattern-matching-and-guards.md)
+3. [09: モジュール設計とビヘイビア](./09-module-design-and-behaviours.md)
+
+### 第 4 部: 関数型プログラミング
+
+1. [10: 高階関数とパイプライン演算子](./10-higher-order-functions-and-pipeline-operator.md)
+2. [11: Stream と遅延評価](./11-stream-and-lazy-evaluation.md)
+3. [12: エラーハンドリングと with 構文](./12-error-handling-and-with-expression.md)

package/lib/assets/docs/article/getting-start-tdd/fsharp/chapter01.md

@@ -0,0 +1,202 @@
+# 第 1 章: TODO リストと最初のテスト
+
+## 1.1 はじめに
+
+プログラムを作成するにあたって、まず何をすればよいでしょうか？私たちは、仕様を確認して **TODO リスト** を作るところから始めます。
+
+> TODO リスト
+>
+> 何をテストすべきだろうか——着手する前に、必要になりそうなテストをリストに書き出しておこう。
+>
+> — テスト駆動開発
+
+## 1.2 仕様の確認
+
+今回取り組む FizzBuzz 問題の仕様は以下の通りです。
+
+```
+1 から 100 までの数をプリントするプログラムを書け。
+ただし 3 の倍数のときは数の代わりに「Fizz」と、5 の倍数のときは「Buzz」とプリントし、
+3 と 5 両方の倍数の場合には「FizzBuzz」とプリントすること。
+```
+
+この仕様をそのままプログラムに落とし込むには少しサイズが大きいですね。最初の作業は仕様を **TODO リスト** に分解する作業から着手しましょう。
+
+## 1.3 TODO リストの作成
+
+仕様を分解して TODO リストを作成します。
+
+**TODO リスト**:
+
+- [ ] 数を文字列にして返す
+  - [ ] 1 を渡したら文字列 "1" を返す
+- [ ] 3 の倍数のときは数の代わりに「Fizz」と返す
+- [ ] 5 の倍数のときは「Buzz」と返す
+- [ ] 3 と 5 両方の倍数の場合には「FizzBuzz」と返す
+- [ ] 1 から 100 までの数
+- [ ] プリントする
+
+まず「1 を渡したら文字列 "1" を返す」という、最も小さなタスクから取り掛かります。
+
+## 1.4 テスティングフレームワークの導入
+
+### テストファースト
+
+最初にプログラムする対象を決めたので、早速プロダクトコードを実装……ではなく **テストファースト** で作業を進めましょう。
+
+> テストファースト
+>
+> いつテストを書くべきだろうか——それはテスト対象のコードを書く前だ。
+>
+> — テスト駆動開発
+
+今回 F# のテスティングフレームワークには **xUnit** を利用します。xUnit は .NET エコシステムで広く使われているテスティングフレームワークです。
+
+### 開発環境のセットアップ
+
+dotnet CLI で F# プロジェクトを作成します。
+
+```bash
+# Nix 環境に入る
+$ nix develop .#dotnet
+
+# ライブラリプロジェクトの作成
+$ dotnet new classlib -lang F# -n FizzBuzzFSharp
+$ cd FizzBuzzFSharp
+
+# テストプロジェクトの作成
+$ cd ..
+$ dotnet new xunit -lang F# -n FizzBuzzFSharpTest
+$ cd FizzBuzzFSharpTest
+$ dotnet add reference ../FizzBuzzFSharp/FizzBuzzFSharp.fsproj
+```
+
+F# のテストは xUnit の `[<Fact>]` アトリビュートを付けた関数として記述します。関数名にはダブルバッククォートで囲むことで日本語を使用できます。
+
+### 環境確認テスト
+
+環境が正しく設定されていることを確認するため、学習用テストを書きます。
+
+```fsharp
+// Tests.fs
+module Tests
+
+open Xunit
+
+[<Fact>]
+let ``整数を文字列へ変換できる`` () =
+    Assert.Equal("42", string 42)
+```
+
+テストを実行します。
+
+```bash
+$ dotnet test
+  合計: 1、成功: 1、失敗: 0、スキップ: 0
+```
+
+テストが通りました。F# の `string` 関数が整数を文字列に変換できることを確認しました。`let` バインディングで関数を定義し、`Assert.Equal` で期待値と実際の値を比較します。
+
+## 1.5 仮実装
+
+テスト環境の準備ができたので、TODO リストの最初の作業に取り掛かりましょう。
+
+**TODO リスト**:
+
+- [ ] 数を文字列にして返す
+  - **1 を渡したら文字列 "1" を返す**
+
+まずはアサーションを最初に書きましょう。
+
+> アサートファースト
+>
+> いつアサーションを書くべきだろうか——最初に書こう。
+>
+> — テスト駆動開発
+
+### Red: 最初のテスト
+
+FizzBuzz のテストを書きます。
+
+```fsharp
+// Tests.fs
+module Tests
+
+open Xunit
+open FizzBuzzFSharp.FizzBuzz
+
+[<Fact>]
+let ``数を文字列にして返す_1を渡したら文字列1を返す`` () =
+    Assert.Equal("1", generate 1)
+```
+
+テストを実行します。
+
+```bash
+$ dotnet test
+error FS0039: 値またはコンストラクター 'generate' が定義されていません。
+```
+
+`generate` 関数がまだ定義されていないため、コンパイルエラーになります。これは期待通りの **Red** フェーズです。
+
+### Green: 仮実装
+
+テストを通すために **仮実装** から始めます。
+
+> 仮実装を経て本実装へ
+>
+> 失敗するテストを書いてから、最初に行う実装はどのようなものだろうか——ベタ書きの値を返そう。
+>
+> — テスト駆動開発
+
+`generate` 関数を定義して、文字列リテラルを返します。
+
+```fsharp
+// Library.fs
+namespace FizzBuzzFSharp
+
+module FizzBuzz =
+
+    let generate (number: int) : string =
+        "1"
+```
+
+テストを実行します。
+
+```bash
+$ dotnet test
+  合計: 1、成功: 1、失敗: 0、スキップ: 0
+```
+
+テストが通りました。F# では `let` バインディングで関数を定義します。`module` キーワードでモジュールを定義し、その中に関数をまとめます。型注釈 `(number: int) : string` は省略可能ですが、最初は明示することで意図を明確にします。
+
+**TODO リスト**:
+
+- [ ] 数を文字列にして返す
+  - [x] 1 を渡したら文字列 "1" を返す
+- [ ] 3 の倍数のときは数の代わりに「Fizz」と返す
+- [ ] 5 の倍数のときは「Buzz」と返す
+- [ ] 3 と 5 両方の倍数の場合には「FizzBuzz」と返す
+- [ ] 1 から 100 までの数
+- [ ] プリントする
+
+ここまでの作業をバージョン管理システムにコミットしておきましょう。
+
+```bash
+$ git add .
+$ git commit -m 'test: 数を文字列にして返す'
+```
+
+## 1.6 まとめ
+
+この章では以下のことを学びました。
+
+- **TODO リスト** で仕様をプログラミング対象に分解する方法
+- **テストファースト** で最初にテストを書く考え方
+- F# プロジェクトのセットアップ（dotnet CLI、xUnit）
+- **仮実装** でベタ書きの値を返してテストを通す手法
+- F# の `let` バインディングによる関数定義
+- F# の `module` によるコードの構造化
+- ダブルバッククォートによるテスト関数名への日本語使用
+
+次章では、2 つ目のテストケースを追加して **三角測量** を行い、プログラムを一般化していきます。