@k2works/claude-code-booster 3.0.0 → 3.1.0

package/lib/assets/docs/article/functional-desgin-ppp/haskell/04-data-validation.md

@@ -0,0 +1,257 @@
+# 第4章: データバリデーション
+
+## はじめに
+
+Haskell では型システムと組み合わせて、コンパイル時と実行時の両方でデータの整合性を保証できます。本章では、`Either`、`Validated` パターン、スマートコンストラクタを使ったデータバリデーションの手法を学びます。
+
+## 1. 基本的なバリデーション（Either を使用）
+
+### Either によるバリデーション
+
+`Either a b` は失敗時に `Left`、成功時に `Right` を返す型です：
+
+```haskell
+-- | バリデーションエラー型
+data ValidationError
+    = EmptyValue String
+    | TooShort String Int Int  -- field, actual, minimum
+    | TooLong String Int Int   -- field, actual, maximum
+    | OutOfRange String Int Int Int
+    | InvalidFormat String String
+    deriving (Show, Eq)
+
+-- | バリデーション結果
+type ValidationResult a = Either ValidationError a
+
+-- | 名前のバリデーション
+validateNonEmpty :: String -> String -> ValidationResult String
+validateNonEmpty field value
+    | null value = Left (EmptyValue field)
+    | otherwise = Right value
+
+-- | 年齢のバリデーション
+validateRange :: String -> Int -> Int -> Int -> ValidationResult Int
+validateRange field minVal maxVal value
+    | value < minVal || value > maxVal = Left (OutOfRange field value minVal maxVal)
+    | otherwise = Right value
+
+-- 使用例
+validateNonEmpty "name" "田中"  -- => Right "田中"
+validateNonEmpty "name" ""      -- => Left (EmptyValue "name")
+validateRange "age" 0 150 25    -- => Right 25
+validateRange "age" 0 150 (-1)  -- => Left (OutOfRange "age" (-1) 0 150)
+```
+
+## 2. スマートコンストラクタ
+
+### ドメインプリミティブ
+
+newtypes とスマートコンストラクタを組み合わせて、不正な値を型レベルで防ぎます：
+
+```haskell
+-- | Name ドメイン型
+newtype Name = Name { unName :: String }
+    deriving (Show, Eq)
+
+-- | スマートコンストラクタ
+mkName :: String -> ValidationResult Name
+mkName value = do
+    _ <- validateNonEmpty "name" value
+    _ <- validateMaxLength "name" 100 value
+    Right (Name value)
+
+-- | Age ドメイン型
+newtype Age = Age { unAge :: Int }
+    deriving (Show, Eq)
+
+mkAge :: Int -> ValidationResult Age
+mkAge value = do
+    _ <- validateRange "age" 0 150 value
+    Right (Age value)
+
+-- | Email ドメイン型
+newtype Email = Email { unEmail :: String }
+    deriving (Show, Eq)
+
+mkEmail :: String -> ValidationResult Email
+mkEmail value = do
+    _ <- validateNonEmpty "email" value
+    _ <- validateEmail value
+    Right (Email value)
+
+-- 使用例
+mkName "田中太郎"  -- => Right (Name "田中太郎")
+mkName ""          -- => Left (EmptyValue "name")
+mkAge 25           -- => Right (Age 25)
+mkAge 200          -- => Left (OutOfRange "age" 200 0 150)
+```
+
+## 3. Validated パターン（エラー蓄積）
+
+`Either` は最初のエラーで停止しますが、すべてのエラーを収集したい場合は `Validated` パターンを使用：
+
+```haskell
+-- | Validated 型
+data Validated a
+    = Valid a
+    | Invalid [ValidationError]
+    deriving (Show, Eq)
+
+instance Functor Validated where
+    fmap f (Valid a) = Valid (f a)
+    fmap _ (Invalid es) = Invalid es
+
+instance Applicative Validated where
+    pure = Valid
+    Valid f <*> Valid a = Valid (f a)
+    Invalid es1 <*> Invalid es2 = Invalid (es1 ++ es2)  -- エラーを蓄積
+    Invalid es <*> _ = Invalid es
+    _ <*> Invalid es = Invalid es
+
+-- | Either から Validated への変換
+fromResult :: ValidationResult a -> Validated a
+fromResult (Right a) = Valid a
+fromResult (Left e) = Invalid [e]
+
+-- 使用例：複数フィールドの検証
+validatePersonV :: String -> Int -> String -> Validated (Name, Age, Email)
+validatePersonV name age email =
+    (,,) <$> fromResult (mkName name)
+         <*> fromResult (mkAge age)
+         <*> fromResult (mkEmail email)
+
+-- 有効なデータ
+validatePersonV "田中" 30 "tanaka@example.com"
+-- => Valid (Name "田中", Age 30, Email "tanaka@example.com")
+
+-- 複数のエラー
+validatePersonV "" (-5) "invalid"
+-- => Invalid [EmptyValue "name", OutOfRange "age" (-5) 0 150, InvalidFormat "email" "invalid"]
+```
+
+## 4. 列挙型とパーサー
+
+```haskell
+-- | 会員種別
+data Membership = Bronze | Silver | Gold | Platinum
+    deriving (Show, Eq, Ord, Enum, Bounded)
+
+-- | 文字列からパース
+parseMembership :: String -> ValidationResult Membership
+parseMembership s = case map toLower s of
+    "bronze" -> Right Bronze
+    "silver" -> Right Silver
+    "gold" -> Right Gold
+    "platinum" -> Right Platinum
+    _ -> Left (InvalidValue "membership" ("unknown: " ++ s))
+
+-- | 文字列へ変換
+membershipToString :: Membership -> String
+membershipToString Bronze = "bronze"
+membershipToString Silver = "silver"
+membershipToString Gold = "gold"
+membershipToString Platinum = "platinum"
+```
+
+## 5. 複合データのバリデーション
+
+### Person バリデーション
+
+```haskell
+-- | Person レコード
+data Person = Person
+    { personName :: Name
+    , personAge  :: Age
+    , personEmail :: Maybe Email
+    , personMembership :: Maybe Membership
+    } deriving (Show, Eq)
+
+-- | 入力データ
+data PersonInput = PersonInput
+    { inputName :: String
+    , inputAge :: Int
+    , inputEmail :: Maybe String
+    , inputMembership :: Maybe String
+    } deriving (Show, Eq)
+
+-- | バリデーション（do 記法で連鎖）
+validatePerson :: PersonInput -> ValidationResult Person
+validatePerson input = do
+    name <- mkName (inputName input)
+    age <- mkAge (inputAge input)
+    email <- traverse mkEmail (inputEmail input)
+    membership <- traverse parseMembership (inputMembership input)
+    Right Person
+        { personName = name
+        , personAge = age
+        , personEmail = email
+        , personMembership = membership
+        }
+```
+
+### 注文バリデーション
+
+```haskell
+-- | 商品ID（PROD-XXXXX形式）
+newtype ProductId = ProductId { unProductId :: String }
+    deriving (Show, Eq)
+
+mkProductId :: String -> ValidationResult ProductId
+mkProductId value
+    | length value == 10 &&
+      take 5 value == "PROD-" &&
+      all isDigit (drop 5 value) = Right (ProductId value)
+    | otherwise = Left (InvalidFormat "product ID" value)
+
+-- | 商品
+data Product = Product
+    { productId :: ProductId
+    , productName :: String
+    , productPrice :: Int
+    } deriving (Show, Eq)
+
+-- | 注文アイテム
+data OrderItem = OrderItem
+    { orderItemProduct :: Product
+    , orderItemQuantity :: Int
+    } deriving (Show, Eq)
+
+-- | 注文
+data Order = Order
+    { orderItems :: [OrderItem]
+    , orderCustomer :: Person
+    } deriving (Show, Eq)
+```
+
+## 6. まとめ
+
+```plantuml
+@startuml
+title Haskell バリデーションパターン
+
+package "Either (Fail-Fast)" {
+    [Left error] --> [最初のエラーで停止]
+    [Right value] --> [成功値]
+}
+
+package "Validated (Accumulating)" {
+    [Invalid errors] --> [全エラーを収集]
+    [Valid value] --> [成功値]
+}
+
+package "Smart Constructors" {
+    [newtype Name] --> [mkName :: String -> ValidationResult Name]
+    [newtype Age] --> [mkAge :: Int -> ValidationResult Age]
+}
+
+[Either (Fail-Fast)] --> [do 記法で連鎖]
+[Validated (Accumulating)] --> [Applicative で並列]
+@enduml
+```
+
+| パターン | 用途 | 特徴 |
+|---------|------|------|
+| Either | 順次バリデーション | 最初のエラーで停止 |
+| Validated | 並列バリデーション | すべてのエラーを収集 |
+| Smart Constructor | ドメインプリミティブ | 型安全な値の作成 |
+| newtype | 型の区別 | ランタイムコストなし |

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

@@ -0,0 +1,254 @@
+# 第5章: プロパティベーステスト
+
+## はじめに
+
+従来の単体テストでは特定の入力に対する出力を検証しますが、**プロパティベーステスト**では、すべての入力に対して成り立つべき「性質（プロパティ）」を定義し、ランダムに生成された多数のテストケースで検証します。
+
+Haskell では QuickCheck ライブラリを使用してプロパティベーステストを行います。
+
+## 1. プロパティベーステストとは
+
+### 従来のテストとの違い
+
+```haskell
+-- 従来のテスト：特定の入力に対する出力を検証
+spec :: Spec
+spec = do
+    it "reverses 'hello' to 'olleh'" $
+        reverseString "hello" `shouldBe` "olleh"
+    it "reverses empty string" $
+        reverseString "" `shouldBe` ""
+
+-- プロパティベーステスト：性質を検証
+spec :: Spec
+spec = do
+    it "reversing twice returns original" $ property $
+        \s -> reverseString (reverseString s) == (s :: String)
+```
+
+### プロパティベーステストの利点
+
+1. **網羅性**: 手動では思いつかないエッジケースを発見
+2. **ドキュメント性**: コードの性質を明確に表現
+3. **回帰防止**: リファクタリング時の安全網
+4. **シュリンキング**: 失敗時に最小の反例を提示
+
+## 2. QuickCheck の基本
+
+### 基本的なプロパティ
+
+```haskell
+import Test.QuickCheck
+
+-- 文字列の反転
+prop_reverseInvolutory :: String -> Bool
+prop_reverseInvolutory s = reverse (reverse s) == s
+
+-- 長さの保存
+prop_reversePreservesLength :: String -> Bool
+prop_reversePreservesLength s = length (reverse s) == length s
+
+-- テスト実行
+main = do
+    quickCheck prop_reverseInvolutory
+    -- +++ OK, passed 100 tests.
+```
+
+### 条件付きプロパティ（==>）
+
+```haskell
+-- 正の数に対してのみテスト
+prop_sqrtPositive :: Int -> Property
+prop_sqrtPositive n = n > 0 ==> sqrt (fromIntegral n) >= 0
+
+-- FizzBuzz: 3の倍数のみ
+prop_fizzForMultiplesOf3Only :: Positive Int -> Property
+prop_fizzForMultiplesOf3Only (Positive n) =
+    let num = n * 3
+    in num `mod` 5 /= 0 ==> fizzBuzz num == "Fizz"
+```
+
+## 3. リスト関数のプロパティ
+
+### ソートのプロパティ
+
+```haskell
+-- ソート結果は整列済み
+prop_sortedIsSorted :: [Int] -> Bool
+prop_sortedIsSorted xs = isSorted (sort xs)
+  where
+    isSorted [] = True
+    isSorted [_] = True
+    isSorted (x:y:rest) = x <= y && isSorted (y:rest)
+
+-- ソート結果は同じ長さ
+prop_sortPreservesLength :: [Int] -> Bool
+prop_sortPreservesLength xs = length (sort xs) == length xs
+
+-- ソートは冪等
+prop_sortIdempotent :: [Int] -> Bool
+prop_sortIdempotent xs = sort (sort xs) == sort xs
+
+-- ソート結果は同じ要素を持つ
+prop_sortSameElements :: [Int] -> Bool
+prop_sortSameElements xs = sort (sort xs) == sort xs
+```
+
+### フィルターのプロパティ
+
+```haskell
+-- フィルター結果はすべて述語を満たす
+prop_filterAllSatisfy :: [Int] -> Bool
+prop_filterAllSatisfy xs = all even (filter even xs)
+
+-- const True でフィルターは恒等
+prop_filterTrue :: [Int] -> Bool
+prop_filterTrue xs = filter (const True) xs == xs
+
+-- const False でフィルターは空
+prop_filterFalse :: [Int] -> Bool
+prop_filterFalse xs = null (filter (const False) xs)
+```
+
+## 4. 数学関数のプロパティ
+
+### 絶対値
+
+```haskell
+-- 絶対値は非負
+prop_absNonNegative :: Int -> Bool
+prop_absNonNegative n = abs n >= 0
+
+-- 絶対値は冪等
+prop_absIdempotent :: Int -> Bool
+prop_absIdempotent n = abs (abs n) == abs n
+
+-- 負数の絶対値
+prop_absOfNegative :: Positive Int -> Bool
+prop_absOfNegative (Positive n) = abs (-n) == n
+```
+
+### 階乗
+
+```haskell
+-- 階乗は正（非負入力に対して）
+prop_factorialPositive :: NonNegative Int -> Bool
+prop_factorialPositive (NonNegative n) =
+    let n' = min n 20  -- 大きい数を避ける
+    in factorial n' > 0
+
+-- フィボナッチの漸化式
+prop_fibRecurrence :: NonNegative Int -> Bool
+prop_fibRecurrence (NonNegative n) =
+    let n' = min n 20
+    in n' < 2 || fibonacci n' == fibonacci (n' - 1) + fibonacci (n' - 2)
+```
+
+## 5. 代数的性質
+
+### Money 型の演算
+
+```haskell
+data Money = Money { amount :: Int, currency :: String }
+    deriving (Show, Eq)
+
+-- 加算の可換性
+prop_addCommutative :: Int -> Int -> Bool
+prop_addCommutative a1 a2 =
+    let m1 = Money a1 "JPY"
+        m2 = Money a2 "JPY"
+    in addMoney m1 m2 == addMoney m2 m1
+
+-- 加算の結合性
+prop_addAssociative :: Int -> Int -> Int -> Bool
+prop_addAssociative a1 a2 a3 =
+    let m1 = Money a1 "JPY"
+        m2 = Money a2 "JPY"
+        m3 = Money a3 "JPY"
+        left = addMoney m1 m2 >>= \s -> addMoney s m3
+        right = addMoney m2 m3 >>= \s -> addMoney m1 s
+    in left == right
+
+-- 乗算の単位元
+prop_multiplyIdentity :: Int -> Bool
+prop_multiplyIdentity a =
+    let m = Money a "JPY"
+    in multiplyMoney m 1 == m
+
+-- 乗算の零元
+prop_multiplyZero :: Int -> Bool
+prop_multiplyZero a =
+    let m = Money a "JPY"
+    in multiplyMoney m 0 == Money 0 "JPY"
+```
+
+## 6. スタック操作のプロパティ
+
+```haskell
+-- push して pop すると元の要素が返る
+prop_pushPop :: Int -> Bool
+prop_pushPop x =
+    let s = push x emptyStack
+    in pop s == Just (x, emptyStack)
+
+-- push するとサイズが増える
+prop_pushIncreasesSize :: Int -> [Int] -> Bool
+prop_pushIncreasesSize x xs =
+    let s = foldr push emptyStack xs
+        s' = push x s
+    in size s' == size s + 1
+
+-- isEmpty は空スタックでのみ True
+prop_isEmptyAfterPush :: Int -> Bool
+prop_isEmptyAfterPush x = not (isEmpty (push x emptyStack))
+
+-- peek は pop と同じ要素を返す
+prop_peekEqualsPopFirst :: Int -> Bool
+prop_peekEqualsPopFirst x =
+    let s = push x emptyStack
+    in peek s == fmap fst (pop s)
+```
+
+## 7. ラウンドトリッププロパティ
+
+```haskell
+-- Roman numerals: toRoman と fromRoman の往復
+prop_romanRoundtrip :: Positive Int -> Bool
+prop_romanRoundtrip (Positive n) =
+    let num = (n `mod` 3999) + 1  -- 有効範囲 1-3999
+    in fromRoman (toRoman num) == num
+
+-- 素因数分解: 積は元の数
+prop_primeFactorsProduct :: Positive Int -> Bool
+prop_primeFactorsProduct (Positive n) =
+    let n' = max 2 (n `mod` 1000)
+    in product (primeFactors n') == n'
+```
+
+## 8. まとめ
+
+| プロパティの種類 | 例 |
+|----------------|-----|
+| 冪等性 | `f (f x) == f x` |
+| 恒等性 | `reverse (reverse x) == x` |
+| 可換性 | `f x y == f y x` |
+| 結合性 | `f (f x y) z == f x (f y z)` |
+| 長さ保存 | `length (f xs) == length xs` |
+| 範囲制約 | `f x >= 0` |
+| ラウンドトリップ | `decode (encode x) == x` |
+
+### QuickCheck のヒント
+
+```haskell
+-- カスタム生成器
+genAge :: Gen Int
+genAge = choose (0, 150)
+
+-- サイズ制限
+genSmallList :: Gen [Int]
+genSmallList = resize 10 (listOf arbitrary)
+
+-- NonNegative, Positive などの型ラッパー
+prop_example :: NonNegative Int -> Positive Int -> Bool
+prop_example (NonNegative n) (Positive p) = ...
+```