@k2works/claude-code-booster 3.0.0 → 3.1.0

package/lib/assets/docs/article/functional-desgin-ppp/clojure/04-clojure-spec.md

@@ -0,0 +1,350 @@
+# 第4章: Clojure Spec による仕様定義
+
+## はじめに
+
+Clojure Spec は、データ構造と関数の仕様を定義するための強力なライブラリです。型システムとは異なり、Spec は実行時にデータを検証し、自動テストを生成し、ドキュメントとしても機能します。
+
+本章では、Spec を使ってデータの仕様を定義し、関数の契約を表現し、自動テスト生成を活用する方法を学びます。
+
+## 1. 基本的なスペック定義
+
+### スペックとは
+
+スペックは、データが満たすべき条件を宣言的に定義します。
+
+```clojure
+(require '[clojure.spec.alpha :as s])
+
+;; シンプルなスペック
+(s/def ::name (s/and string? #(< 0 (count %) 100)))
+(s/def ::age (s/and int? #(<= 0 % 150)))
+(s/def ::email (s/and string? #(re-matches #".+@.+\..+" %)))
+
+;; 列挙型のスペック
+(s/def ::membership #{:bronze :silver :gold :platinum})
+(s/def ::status #{:active :inactive :suspended})
+```
+
+### スペックの検証
+
+```clojure
+;; valid? で検証
+(s/valid? ::name "田中太郎")  ;; => true
+(s/valid? ::name "")          ;; => false（空文字列）
+(s/valid? ::age 25)           ;; => true
+(s/valid? ::age -1)           ;; => false（負の数）
+
+;; explain でエラー詳細を表示
+(s/explain ::age -1)
+;; val: -1 fails spec: :user/age predicate: (<= 0 % 150)
+```
+
+## 2. コレクションのスペック
+
+### ベクターとリスト
+
+```clojure
+;; ベクターのスペック
+(s/def ::tags (s/coll-of string? :kind vector? :min-count 0 :max-count 10))
+
+(s/valid? ::tags ["tag1" "tag2"])  ;; => true
+(s/valid? ::tags '("tag1"))        ;; => false（リストは不可）
+```
+
+### マップのスペック
+
+```clojure
+;; 必須キーとオプションキー
+(s/def ::person
+  (s/keys :req-un [::name ::age]
+          :opt-un [::email ::membership]))
+
+(s/valid? ::person {:name "田中" :age 30})  ;; => true
+(s/valid? ::person {:name "田中" :age 30 :email "tanaka@example.com"})  ;; => true
+(s/valid? ::person {:name "田中"})  ;; => false（age が欠落）
+```
+
+### 入れ子のマップ
+
+```clojure
+(s/def ::street string?)
+(s/def ::city string?)
+(s/def ::postal-code (s/and string? #(re-matches #"\d{3}-\d{4}" %)))
+
+(s/def ::address
+  (s/keys :req-un [::street ::city ::postal-code]))
+
+(s/def ::person-with-address
+  (s/keys :req-un [::name ::age ::address]))
+
+(s/valid? ::person-with-address
+          {:name "田中"
+           :age 30
+           :address {:street "東京都渋谷区1-1-1"
+                     :city "渋谷区"
+                     :postal-code "150-0001"}})
+;; => true
+```
+
+## 3. ドメインモデルの定義
+
+### 商品と注文
+
+```clojure
+;; 商品
+(s/def ::product-id (s/and string? #(re-matches #"PROD-\d{5}" %)))
+(s/def ::product-name (s/and string? #(< 0 (count %) 200)))
+(s/def ::price (s/and number? pos?))
+(s/def ::quantity (s/and int? pos?))
+
+(s/def ::product
+  (s/keys :req-un [::product-id ::product-name ::price]
+          :opt-un [::description ::category]))
+
+;; 注文アイテム
+(s/def ::order-item
+  (s/keys :req-un [::product-id ::quantity ::price]))
+
+;; 注文
+(s/def ::order-id (s/and string? #(re-matches #"ORD-\d{8}" %)))
+(s/def ::customer-id (s/and string? #(re-matches #"CUST-\d{6}" %)))
+(s/def ::items (s/coll-of ::order-item :min-count 1))
+
+(s/def ::order
+  (s/keys :req-un [::order-id ::customer-id ::items ::order-date]
+          :opt-un [::total ::status]))
+```
+
+## 4. 関数仕様の定義（fdef）
+
+### 基本的な fdef
+
+`s/fdef` を使って関数の引数、戻り値、および引数と戻り値の関係を定義します。
+
+```clojure
+(defn calculate-item-total
+  "注文アイテムの合計を計算する"
+  [{:keys [price quantity]}]
+  (* price quantity))
+
+(s/fdef calculate-item-total
+  :args (s/cat :item ::order-item)
+  :ret number?
+  :fn (s/and #(pos? (:ret %))
+             #(= (:ret %)
+                 (* (get-in % [:args :item :price])
+                    (get-in % [:args :item :quantity])))))
+```
+
+### fdef の構成要素
+
+- **:args**: 引数のスペック（`s/cat` で名前付き引数を定義）
+- **:ret**: 戻り値のスペック
+- **:fn**: 引数と戻り値の関係を定義する述語
+
+```clojure
+(defn apply-discount
+  "割引を適用する"
+  [total discount-rate]
+  (* total (- 1 discount-rate)))
+
+(s/fdef apply-discount
+  :args (s/cat :total ::total :discount-rate (s/and number? #(<= 0 % 1)))
+  :ret number?
+  :fn #(<= (:ret %) (get-in % [:args :total])))  ;; 戻り値は元の値以下
+```
+
+## 5. 多引数と可変長引数
+
+### オーバーロードされた関数
+
+```clojure
+(defn create-person
+  "人物を作成する"
+  ([name age]
+   {:name name :age age})
+  ([name age email]
+   {:name name :age age :email email}))
+
+(s/fdef create-person
+  :args (s/alt :two-args (s/cat :name ::name :age ::age)
+               :three-args (s/cat :name ::name :age ::age :email ::email))
+  :ret ::person)
+```
+
+### 可変長引数
+
+```clojure
+(defn sum-prices
+  "複数の価格を合計する"
+  [& prices]
+  (reduce + 0 prices))
+
+(s/fdef sum-prices
+  :args (s/* ::price)
+  :ret number?)
+```
+
+## 6. 条件付きスペック（マルチスペック）
+
+データの内容に応じて異なるスペックを適用する場合は、マルチスペックを使用します。
+
+```clojure
+(s/def ::notification-type #{:email :sms :push})
+
+(defmulti notification-spec :type)
+
+(defmethod notification-spec :email [_]
+  (s/keys :req-un [::type ::to ::subject ::body]))
+
+(defmethod notification-spec :sms [_]
+  (s/keys :req-un [::type ::phone-number ::body]))
+
+(defmethod notification-spec :push [_]
+  (s/keys :req-un [::type ::device-token ::body]))
+
+(s/def ::notification (s/multi-spec notification-spec :type))
+
+;; 検証
+(s/valid? ::notification
+          {:type :email
+           :to "test@example.com"
+           :subject "テスト"
+           :body "本文"})
+;; => true
+
+(s/valid? ::notification
+          {:type :sms
+           :phone-number "090-1234-5678"
+           :body "本文"})
+;; => true
+```
+
+## 7. カスタムジェネレータ
+
+スペックに対応するテストデータを自動生成するジェネレータを定義できます。
+
+```clojure
+(require '[clojure.spec.gen.alpha :as gen])
+
+(defn product-id-gen
+  "商品IDのジェネレータ"
+  []
+  (gen/fmap #(str "PROD-" (format "%05d" %))
+            (gen/choose 0 99999)))
+
+(s/def ::product-id-with-gen
+  (s/with-gen
+    (s/and string? #(re-matches #"PROD-\d{5}" %))
+    product-id-gen))
+
+;; サンプル生成
+(gen/sample (s/gen ::product-id-with-gen) 5)
+;; => ("PROD-00042" "PROD-00001" "PROD-12345" "PROD-00000" "PROD-99999")
+```
+
+### メールアドレスのジェネレータ
+
+```clojure
+(defn email-gen
+  "メールアドレスのジェネレータ"
+  []
+  (gen/fmap (fn [[user domain]]
+              (str user "@" domain ".com"))
+            (gen/tuple (gen/such-that #(not (empty? %))
+                                       (gen/string-alphanumeric))
+                       (gen/such-that #(not (empty? %))
+                                       (gen/string-alphanumeric)))))
+```
+
+## 8. バリデーションとエラーハンドリング
+
+### バリデーション関数
+
+```clojure
+(defn validate-person
+  "人物データを検証し、結果を返す"
+  [person]
+  (if (s/valid? ::person person)
+    {:valid true :data person}
+    {:valid false
+     :errors (s/explain-data ::person person)}))
+
+(validate-person {:name "田中" :age 30})
+;; => {:valid true, :data {:name "田中", :age 30}}
+
+(validate-person {:name "" :age 30})
+;; => {:valid false, :errors {...}}
+```
+
+### conform による値の変換
+
+```clojure
+(defn conform-or-throw
+  "スペックに適合しない場合は例外をスロー"
+  [spec data]
+  (let [conformed (s/conform spec data)]
+    (if (= conformed ::s/invalid)
+      (throw (ex-info "Validation failed"
+                      {:spec spec
+                       :data data
+                       :problems (s/explain-data spec data)}))
+      conformed)))
+```
+
+## 9. インストルメンテーション
+
+開発時に関数の引数を自動検証できます。
+
+```clojure
+(require '[clojure.spec.test.alpha :as stest])
+
+;; インストルメンテーションを有効化
+(stest/instrument)
+
+;; これ以降、fdef が定義された関数は引数が自動検証される
+(calculate-item-total {:product-id "INVALID" :quantity -1 :price 0})
+;; => ExceptionInfo: Call to #'user/calculate-item-total did not conform to spec
+
+;; 無効化
+(stest/unstrument)
+```
+
+## 10. テスト生成
+
+`check` 関数で自動的にテストを生成・実行できます。
+
+```clojure
+(stest/check `calculate-item-total)
+;; 100個のランダムな入力でテストを実行
+
+(stest/check `apply-discount {:clojure.spec.test.check/opts {:num-tests 1000}})
+;; 1000個のテストケースで実行
+```
+
+## まとめ
+
+本章では、Clojure Spec について学びました：
+
+1. **基本的なスペック**: 述語と組み合わせたデータ検証
+2. **コレクションスペック**: ベクター、マップの構造定義
+3. **ドメインモデル**: ビジネスデータの仕様定義
+4. **fdef**: 関数の契約（引数、戻り値、関係）
+5. **マルチスペック**: 条件付きの仕様定義
+6. **カスタムジェネレータ**: テストデータの自動生成
+7. **バリデーション**: 実行時検証とエラーハンドリング
+8. **インストルメンテーション**: 開発時の自動検証
+9. **テスト生成**: 自動プロパティベーステスト
+
+Spec を活用することで、動的型付け言語の柔軟性を保ちながら、堅牢なデータ検証とドキュメント化を実現できます。
+
+## 参考コード
+
+本章のコード例は以下のファイルで確認できます：
+
+- ソースコード: `apps/clojure/part2/src/clojure_spec.clj`
+- テストコード: `apps/clojure/part2/spec/clojure_spec_spec.clj`
+
+## 次章予告
+
+次章では、**プロパティベーステスト**について学びます。test.check を使った生成的テストの手法を探ります。

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

@@ -0,0 +1,352 @@
+# 第5章: プロパティベーステスト
+
+## はじめに
+
+従来の単体テストでは、特定の入力に対する期待される出力を検証します。一方、**プロパティベーステスト**では、すべての入力に対して成り立つべき「性質（プロパティ）」を定義し、ランダムに生成された多数のテストケースで検証します。
+
+本章では、Clojure の `test.check` ライブラリを使ったプロパティベーステストの手法を学びます。
+
+## 1. プロパティベーステストとは
+
+### 従来のテストとの違い
+
+```clojure
+;; 従来のテスト：特定の入力に対する出力を検証
+(deftest test-reverse
+  (is (= "olleh" (reverse-string "hello")))
+  (is (= "" (reverse-string "")))
+  (is (= "a" (reverse-string "a"))))
+
+;; プロパティベーステスト：性質を検証
+(def prop-reverse-involutory
+  "文字列を2回反転すると元に戻る"
+  (prop/for-all [s gen/string]
+    (= s (reverse-string (reverse-string s)))))
+```
+
+### プロパティベーステストの利点
+
+1. **網羅性**: 手動では思いつかないエッジケースを発見
+2. **ドキュメント性**: コードの性質を明確に表現
+3. **回帰防止**: リファクタリング時の安全網
+4. **シュリンキング**: 失敗時に最小の反例を提示
+
+## 2. 基本的なジェネレータ
+
+### プリミティブジェネレータ
+
+```clojure
+(require '[clojure.test.check.generators :as gen])
+
+;; 整数
+gen/small-integer  ;; -200〜200程度の整数
+gen/nat            ;; 自然数（0以上）
+gen/pos-int        ;; 正の整数
+gen/neg-int        ;; 負の整数
+
+;; 文字列
+gen/string                ;; 任意の文字列
+gen/string-alphanumeric   ;; 英数字のみ
+
+;; その他
+gen/boolean        ;; true/false
+gen/char           ;; 文字
+gen/keyword        ;; キーワード
+
+;; サンプル生成
+(gen/sample gen/small-integer 5)
+;; => (0 1 -2 1 4)
+```
+
+### 範囲と列挙
+
+```clojure
+;; 範囲指定
+(def age-gen (gen/choose 0 150))
+
+;; 浮動小数点数
+(def percentage-gen (gen/double* {:min 0.0 :max 1.0}))
+
+;; 列挙型
+(def membership-gen (gen/elements [:bronze :silver :gold :platinum]))
+```
+
+## 3. コレクションジェネレータ
+
+### ベクター・リスト
+
+```clojure
+;; ベクター
+(gen/vector gen/small-integer)       ;; 任意長
+(gen/vector gen/small-integer 1 10)  ;; 1〜10要素
+
+;; リスト
+(gen/list gen/small-integer)
+
+;; 非空コレクション
+(gen/not-empty (gen/vector gen/small-integer))
+```
+
+### マップとセット
+
+```clojure
+;; マップ
+(gen/map gen/string-alphanumeric gen/small-integer)
+
+;; セット
+(gen/set gen/small-integer)
+
+;; 構造化されたマップ
+(gen/hash-map
+  :name gen/string-alphanumeric
+  :age (gen/choose 0 150)
+  :active gen/boolean)
+```
+
+## 4. 複合ジェネレータ
+
+### ドメインモデルのジェネレータ
+
+```clojure
+(def person-gen
+  "人物データのジェネレータ"
+  (gen/hash-map
+   :name (gen/such-that #(not (empty? %)) gen/string-alphanumeric)
+   :age (gen/choose 0 150)
+   :membership (gen/elements [:bronze :silver :gold :platinum])))
+
+(def product-gen
+  "商品データのジェネレータ"
+  (gen/hash-map
+   :product-id (gen/fmap #(str "PROD-" (format "%05d" (mod % 100000))) gen/nat)
+   :name (gen/such-that #(not (empty? %)) gen/string-alphanumeric)
+   :price (gen/fmap #(+ 1 (mod % 10000)) gen/nat)
+   :quantity (gen/fmap #(+ 1 (mod % 100)) gen/nat)))
+
+(gen/sample product-gen 3)
+;; => ({:product-id "PROD-00000", :name "a", :price 1, :quantity 1}
+;;     {:product-id "PROD-00001", :name "Ab", :price 2, :quantity 2}
+;;     {:product-id "PROD-00003", :name "x2Y", :price 4, :quantity 3})
+```
+
+## 5. ジェネレータの変換
+
+### fmap: 値の変換
+
+```clojure
+;; 生成された値を変換
+(def uppercase-string-gen
+  (gen/fmap clojure.string/upper-case gen/string-alphanumeric))
+
+;; フォーマットされたID
+(def order-id-gen
+  (gen/fmap #(str "ORD-" (format "%08d" %))
+            (gen/choose 0 99999999)))
+```
+
+### bind: 依存関係のある生成
+
+```clojure
+;; 生成された値に基づいて別のジェネレータを選択
+(def non-empty-subset-gen
+  (gen/bind (gen/not-empty (gen/vector gen/small-integer))
+            (fn [v]
+              (gen/fmap #(take % v)
+                        (gen/choose 1 (count v))))))
+```
+
+### such-that: フィルタリング
+
+```clojure
+;; 条件を満たす値のみを生成
+(def positive-even-gen
+  (gen/such-that #(and (pos? %) (even? %)) gen/small-integer 100))
+```
+
+## 6. プロパティの定義
+
+### 基本的なプロパティ
+
+```clojure
+(require '[clojure.test.check.properties :as prop])
+
+;; 文字列反転の性質
+(def prop-reverse-involutory
+  "文字列を2回反転すると元に戻る"
+  (prop/for-all [s gen/string]
+    (= s (reverse-string (reverse-string s)))))
+
+(def prop-reverse-length-preserved
+  "反転しても長さは変わらない"
+  (prop/for-all [s gen/string]
+    (= (count s) (count (reverse-string s)))))
+```
+
+### ソートの性質
+
+```clojure
+(def prop-sort-idempotent
+  "ソートは冪等（2回ソートしても結果は同じ）"
+  (prop/for-all [nums (gen/vector gen/small-integer)]
+    (= (sort-numbers nums) (sort-numbers (sort-numbers nums)))))
+
+(def prop-sort-preserves-elements
+  "ソートは要素を保存する（追加も削除もしない）"
+  (prop/for-all [nums (gen/vector gen/small-integer)]
+    (= (frequencies nums) (frequencies (sort-numbers nums)))))
+
+(def prop-sort-ordered
+  "ソート結果は昇順に並ぶ"
+  (prop/for-all [nums (gen/vector gen/small-integer)]
+    (let [sorted (sort-numbers nums)]
+      (or (empty? sorted)
+          (apply <= sorted)))))
+```
+
+### ビジネスロジックの性質
+
+```clojure
+(def prop-discount-bounds
+  "割引後の価格は0以上、元の価格以下"
+  (prop/for-all [price (gen/fmap #(Math/abs %) gen/small-integer)
+                 rate (gen/double* {:min 0.0 :max 1.0})]
+    (let [discounted (calculate-discount price rate)]
+      (and (>= discounted 0)
+           (<= discounted price)))))
+```
+
+## 7. プロパティの実行
+
+### quick-check
+
+```clojure
+(require '[clojure.test.check :as tc])
+
+;; 100回テスト
+(tc/quick-check 100 prop-reverse-involutory)
+;; => {:result true, :pass? true, :num-tests 100, :time-elapsed-ms 15, ...}
+
+;; 1000回テスト
+(tc/quick-check 1000 prop-sort-ordered)
+```
+
+### 失敗時の出力
+
+```clojure
+;; バグのある関数
+(defn buggy-abs [n]
+  (if (neg? n) (- n) n))
+
+(def prop-abs-positive
+  (prop/for-all [n gen/small-integer]
+    (>= (buggy-abs n) 0)))
+
+(tc/quick-check 10000 prop-abs-positive)
+;; Integer/MIN_VALUE で失敗する場合、シュリンキングで最小反例を提示
+```
+
+## 8. シュリンキング
+
+テストが失敗すると、test.check は自動的に**シュリンキング**を行い、同じ失敗を引き起こす最小の入力を探します。
+
+```clojure
+;; 例：リストの長さが5未満というバグのあるプロパティ
+(def prop-buggy
+  (prop/for-all [v (gen/vector gen/small-integer)]
+    (< (count v) 5)))
+
+(tc/quick-check 100 prop-buggy)
+;; => {:result false,
+;;     :pass? false,
+;;     :shrunk {:total-nodes-visited 7,
+;;              :smallest [[0 0 0 0 0]]},  ;; 最小の反例
+;;     ...}
+```
+
+シュリンキングにより、「長さ100のリストで失敗」ではなく「長さ5のリストで失敗」という最小の反例が得られます。
+
+## 9. ラウンドトリッププロパティ
+
+エンコード/デコードの可逆性は典型的なプロパティです。
+
+```clojure
+(defn encode-run-length [s]
+  (->> s
+       (partition-by identity)
+       (map (fn [group] [(first group) (count group)]))
+       (into [])))
+
+(defn decode-run-length [encoded]
+  (->> encoded
+       (mapcat (fn [[ch n]] (repeat n ch)))
+       (apply str)))
+
+(def prop-run-length-roundtrip
+  "ランレングス符号化は可逆"
+  (prop/for-all [s (gen/fmap #(apply str %) (gen/vector gen/char-alpha))]
+    (= s (decode-run-length (encode-run-length s)))))
+```
+
+## 10. 実践的なパターン
+
+### 代数的性質
+
+```clojure
+;; 結合律
+(def prop-addition-associative
+  (prop/for-all [a gen/small-integer
+                 b gen/small-integer
+                 c gen/small-integer]
+    (= (+ (+ a b) c) (+ a (+ b c)))))
+
+;; 交換律
+(def prop-addition-commutative
+  (prop/for-all [a gen/small-integer
+                 b gen/small-integer]
+    (= (+ a b) (+ b a))))
+```
+
+### オラクルテスト
+
+既知の正しい実装と比較します。
+
+```clojure
+(def prop-my-sort-matches-builtin
+  "自作ソートは組み込みソートと同じ結果"
+  (prop/for-all [nums (gen/vector gen/small-integer)]
+    (= (my-sort nums) (sort nums))))
+```
+
+### 不変条件
+
+```clojure
+(def prop-order-total-positive
+  "注文合計は常に正"
+  (prop/for-all [order order-gen]
+    (pos? (calculate-order-total order))))
+```
+
+## まとめ
+
+本章では、プロパティベーステストについて学びました：
+
+1. **ジェネレータ**: テストデータの自動生成
+2. **プリミティブ**: 整数、文字列、ブール値など
+3. **コレクション**: ベクター、マップ、セット
+4. **変換**: fmap, bind, such-that による加工
+5. **プロパティ**: すべての入力で成り立つべき性質
+6. **シュリンキング**: 失敗時の最小反例探索
+7. **パターン**: ラウンドトリップ、代数的性質、オラクルテスト
+
+プロパティベーステストは、従来のテストを補完し、より堅牢なソフトウェアを実現します。
+
+## 参考コード
+
+本章のコード例は以下のファイルで確認できます：
+
+- ソースコード: `apps/clojure/part2/src/property_based_testing.clj`
+- テストコード: `apps/clojure/part2/spec/property_based_testing_spec.clj`
+
+## 次章予告
+
+次章では、**テスト駆動開発と関数型プログラミング**について学びます。Red-Green-Refactor サイクルを関数型スタイルで実践する方法を探ります。