@k2works/claude-code-booster 2.7.1 → 3.1.0

package/lib/assets/docs/article/getting-start-tdd/haskell/05-package-management-and-static-analysis.md

@@ -0,0 +1,313 @@
+# 第 5 章: パッケージ管理と静的解析
+
+## 5.1 はじめに
+
+Haskell 開発では、依存関係の管理とコード品質の維持を仕組み化することが重要です。
+この章では、Stack と `package.yaml` によるパッケージ管理、HLint による静的解析、GHC コンパイラオプションによる品質管理を扱います。
+
+## 5.2 Stack によるパッケージ管理
+
+### Stack の役割
+
+Stack は Haskell のビルドツール兼パッケージマネージャです。主に次の機能を提供します。
+
+- プロジェクトのビルドとテスト実行
+- 依存パッケージの解決とインストール
+- GHC コンパイラのバージョン管理
+- Stackage スナップショットによる依存関係の一貫性保証
+
+### package.yaml の構成
+
+`apps/haskell/package.yaml` では、プロジェクトの基本情報と依存関係を定義します。
+
+```yaml
+name:                fizzbuzz
+version:             0.1.0.0
+synopsis:            FizzBuzz TDD implementation in Haskell
+description:         A FizzBuzz implementation using Test-Driven Development
+license:             BSD-3-Clause
+author:              k2works
+maintainer:          k2works@example.com
+
+dependencies:
+  - base >= 4.7 && < 5
+
+ghc-options:
+  - -Wall
+  - -Wcompat
+  - -Widentities
+  - -Wincomplete-record-updates
+  - -Wincomplete-uni-patterns
+  - -Wmissing-export-lists
+  - -Wmissing-home-modules
+  - -Wpartial-fields
+  - -Wredundant-constraints
+
+library:
+  source-dirs: src
+  exposed-modules:
+    - FizzBuzz
+
+executables:
+  fizzbuzz:
+    main: Main.hs
+    source-dirs: app
+    dependencies:
+      - fizzbuzz
+
+tests:
+  fizzbuzz-test:
+    main: Spec.hs
+    source-dirs: test
+    dependencies:
+      - fizzbuzz
+      - hspec
+    build-tools:
+      - hspec-discover
+```
+
+各セクションの役割は次の通りです。
+
+| セクション | 説明 |
+|-----------|------|
+| `name` / `version` | パッケージ名とバージョン |
+| `dependencies` | 全体で共通の依存パッケージ |
+| `ghc-options` | コンパイラに渡す警告オプション |
+| `library` | ライブラリとして公開するモジュール |
+| `executables` | 実行可能ファイルの定義 |
+| `tests` | テストスイートの定義 |
+
+`package.yaml` は hpack 形式で、Stack がビルド時に自動的に `.cabal` ファイルへ変換します。そのため `.cabal` ファイルは `.gitignore` に含めています。
+
+### stack.yaml と LTS リゾルバ
+
+`apps/haskell/stack.yaml` では、使用する Stackage スナップショットを指定します。
+
+```yaml
+snapshot: lts-23.20
+
+packages:
+- .
+```
+
+- `snapshot`: Stackage LTS（Long Term Support）のバージョンを指定します。LTS は GHC バージョンと互換性のあるパッケージ群を一式まとめたものです。
+- `packages`: ビルド対象のパッケージディレクトリを指定します。
+
+LTS を固定することで、チーム全員が同じ GHC バージョンと同じパッケージバージョンを使えます。`lts-23.20` は GHC 9.8.4 に対応しています。
+
+### 依存関係の追加方法
+
+テストフレームワーク HSpec を例に、依存関係の追加手順を示します。
+
+**1. package.yaml に依存を追加**
+
+`tests` セクションの `dependencies` に `hspec` を追加します。
+
+```yaml
+tests:
+  fizzbuzz-test:
+    main: Spec.hs
+    source-dirs: test
+    dependencies:
+      - fizzbuzz
+      - hspec
+    build-tools:
+      - hspec-discover
+```
+
+`hspec-discover` は `build-tools` に指定します。これにより、テストファイルの自動検出が有効になります。
+
+**2. テストのエントリポイントを設定**
+
+`test/Spec.hs` に hspec-discover のプラグマを記述します。
+
+```haskell
+{-# OPTIONS_GHC -F -pgmF hspec-discover #-}
+```
+
+この 1 行で、`test/` 配下の `*Spec.hs` ファイルが自動的にテストスイートに組み込まれます。
+
+**3. 依存解決とビルド**
+
+```bash
+stack build --test --no-run-tests
+```
+
+Stack は `stack.yaml` で指定した LTS スナップショットから `hspec` を解決し、ダウンロードします。LTS に含まれるパッケージは `extra-deps` への追記が不要です。
+
+## 5.3 HLint による静的解析
+
+HLint は Haskell の静的解析ツールで、コードの改善提案を行います。
+
+### 基本的な使い方
+
+```bash
+hlint src/ test/ app/
+```
+
+このコマンドで `src/`、`test/`、`app/` 配下の `.hs` ファイルを解析します。
+
+### 検出される問題の例
+
+HLint は次のような改善を提案します。
+
+| カテゴリ | 元のコード | 提案 |
+|---------|-----------|------|
+| 冗長な括弧 | `(f x)` | `f x` |
+| リスト操作 | `head xs` | パターンマッチ `(x:_)` |
+| 関数合成 | `f (g x)` | `(f . g) x` |
+| eta 簡約 | `\x -> f x` | `f` |
+| 不要な `do` | `do { return x }` | `return x` |
+
+実行結果の例:
+
+```
+src/FizzBuzz.hs:8:3: Suggestion: Use otherwise
+Found:
+  generate n | True = show n
+Perhaps:
+  generate n | otherwise = show n
+
+No hints
+```
+
+`No hints` と表示されれば、HLint が検出する問題はありません。
+
+### .hlint.yaml による設定カスタマイズ
+
+`apps/haskell/.hlint.yaml` でルールのカスタマイズが可能です。
+
+```yaml
+# HLint configuration
+# https://github.com/ndmitchell/hlint
+
+- ignore: {name: "Redundant bracket"}
+- ignore: {name: "Use head", within: ["FizzBuzz.FizzBuzzSpec"]}
+```
+
+主な設定項目は次の通りです。
+
+| 設定 | 説明 |
+|------|------|
+| `ignore` | 特定のルールを無効化 |
+| `warn` | 特定のルールを警告として追加 |
+| `error` | 特定のルールをエラーとして追加 |
+| `within` | 適用範囲をモジュール単位で限定 |
+
+テストコードでは `!!` 演算子（リストのインデックスアクセス）を使うことがあるため、`Use head` ルールをテストモジュール内で無効化しています。
+
+## 5.4 コード複雑度チェック
+
+コードの循環複雑度（Cyclomatic Complexity）は、関数内の分岐数に基づいてコードの複雑さを数値化する指標です。複雑度が高い関数はテストが困難で、バグが混入しやすくなります。
+
+### 循環複雑度の計算ルール
+
+| ルール | 説明 |
+|--------|------|
+| 基本複雑度 | 各関数の初期値は 1 |
+| ガード式 `\|` | 各ガードごとに +1 |
+| `if` 式 | 条件分岐ごとに +1 |
+| `case ... of` | case 式の出現ごとに +1 |
+| パターンマッチ分岐 | コンストラクタパターンごとに +1 |
+
+一般的な目安として、1 関数あたり複雑度 **10 以下** が推奨されます。
+
+### カスタム複雑度チェッカー
+
+Haskell には標準的な複雑度チェックツールがないため、`scripts/complexity.sh` にカスタムスクリプトを用意しています。
+
+```bash
+# 実行（デフォルト閾値: 10）
+bash scripts/complexity.sh --threshold 10 src
+
+# 閾値を指定して実行
+bash scripts/complexity.sh --threshold 7 src
+```
+
+実行結果の例:
+
+```
+Checking Haskell complexity (threshold: 10)...
+
+Total functions checked: 2
+Violations: 0
+PASSED: All functions within complexity threshold
+```
+
+### 複雑度が高い場合の対処
+
+複雑度が閾値を超えた場合は、以下のリファクタリングを検討します。
+
+1. **関数分割**: 長いガード式を小さな関数に分解
+2. **パターンマッチの活用**: 条件分岐を代数的データ型のパターンマッチに置き換え
+3. **高階関数の利用**: `if` / ループ的な再帰をコレクション操作（`map` / `filter`）に置き換え
+4. **ガード条件の抽出**: 複雑な条件を `where` 節の補助関数として抽出
+
+## 5.5 GHC コンパイラオプションによる品質管理
+
+`package.yaml` の `ghc-options` セクションで、コンパイル時の警告を設定しています。
+
+```yaml
+ghc-options:
+  - -Wall
+  - -Wcompat
+  - -Widentities
+  - -Wincomplete-record-updates
+  - -Wincomplete-uni-patterns
+  - -Wmissing-export-lists
+  - -Wmissing-home-modules
+  - -Wpartial-fields
+  - -Wredundant-constraints
+```
+
+各オプションの役割は次の通りです。
+
+| オプション | 説明 |
+|-----------|------|
+| `-Wall` | 一般的な警告をすべて有効化 |
+| `-Wcompat` | 将来の GHC バージョンとの互換性警告 |
+| `-Widentities` | 不要な型変換の警告 |
+| `-Wincomplete-record-updates` | レコード更新の網羅性チェック |
+| `-Wincomplete-uni-patterns` | パターンマッチの網羅性チェック |
+| `-Wmissing-export-lists` | エクスポートリスト未指定の警告 |
+| `-Wmissing-home-modules` | モジュール依存の整合性チェック |
+| `-Wpartial-fields` | 部分的なレコードフィールドの警告 |
+| `-Wredundant-constraints` | 不要な型制約の警告 |
+
+特に `-Wall` は Haskell 開発の基本です。型シグネチャの欠落、未使用インポート、パターンマッチの非網羅性など、多くの潜在的問題を検出します。
+
+### 型シグネチャの重要性
+
+`-Wall` を有効にすると、トップレベル関数に型シグネチャがない場合に警告が出ます。
+
+```haskell
+-- 型シグネチャなし（警告が出る）
+generate n
+  | n `mod` 15 == 0 = "FizzBuzz"
+  | n `mod` 3 == 0  = "Fizz"
+  | n `mod` 5 == 0  = "Buzz"
+  | otherwise        = show n
+
+-- 型シグネチャあり（推奨）
+generate :: Int -> String
+generate n
+  | n `mod` 15 == 0 = "FizzBuzz"
+  | n `mod` 3 == 0  = "Fizz"
+  | n `mod` 5 == 0  = "Buzz"
+  | otherwise        = show n
+```
+
+型シグネチャを明示することで、意図しない型推論を防ぎ、コードの可読性が向上します。
+
+## 5.6 まとめ
+
+この章では、Haskell プロジェクトの品質基盤を整えました。
+
+- Stack と `package.yaml` で依存関係を宣言的に管理する
+- `stack.yaml` の LTS リゾルバでパッケージバージョンを統一する
+- HLint で Haskell 固有のイディオムに沿った改善提案を受ける
+- `.hlint.yaml` でプロジェクト固有のルールをカスタマイズする
+- カスタムスクリプトでコード複雑度をチェックする
+- GHC の `-Wall` オプションで型安全性と網羅性を強制する
+
+次章では、これらを Makefile と GitHub Actions で自動実行する方法を扱います。

package/lib/assets/docs/article/getting-start-tdd/haskell/06-task-runner-and-ci-cd.md

@@ -0,0 +1,309 @@
+# 第 6 章: タスクランナーと CI/CD
+
+## 6.1 はじめに
+
+TDD を継続するには、テスト・静的解析・複雑度チェックを毎回確実に実行できる仕組みが必要です。
+この章では、Makefile によるタスク自動化、Nix 開発環境、GitHub Actions を使って開発タスクを自動化します。
+
+## 6.2 Nix による開発環境
+
+本プロジェクトでは Nix Flakes で開発環境を宣言的に管理しています。
+`ops/nix/environments/haskell/shell.nix` に Haskell 環境の定義があります。
+
+```nix
+{ packages ? import <nixpkgs> { } }:
+let
+  baseShell = import ../../shells/shell.nix { inherit packages; };
+in
+packages.mkShell {
+  inputsFrom = [ baseShell ];
+  buildInputs = with packages; [
+    ghc
+    stack
+    cabal-install
+    haskell-language-server
+    hlint
+  ];
+
+  shellHook = baseShell.shellHook + ''
+    echo "Welcome to the Haskell development environment!"
+    ghc --version
+    cabal --version
+    stack --version
+  '';
+}
+```
+
+環境の起動:
+
+```bash
+nix develop .#haskell
+```
+
+これにより、GHC、Stack、Cabal、HLS（Haskell Language Server）、HLint が揃った環境に入れます。
+チーム全員が同じツールバージョンを使えるため、「自分のマシンでは動く」問題を防げます。
+
+### Nix 環境に含まれるツール
+
+| ツール | 用途 |
+|--------|------|
+| `ghc` | Haskell コンパイラ |
+| `stack` | ビルドツール・パッケージマネージャ |
+| `cabal-install` | Cabal ビルドツール |
+| `haskell-language-server` | エディタ統合用 LSP サーバ |
+| `hlint` | 静的解析ツール |
+
+## 6.3 Makefile によるタスク管理
+
+`apps/haskell/Makefile` には、日常的に使うタスクが定義されています。
+
+```makefile
+.PHONY: all build test lint complexity check clean
+
+all: check
+
+build:
+	stack build
+
+test:
+	stack test
+
+lint:
+	hlint src/ test/ app/ -h .hlint.yaml
+
+complexity:
+	bash scripts/complexity.sh --threshold 10 src
+
+check: lint complexity test
+
+clean:
+	stack clean
+```
+
+### 各タスクの説明
+
+| タスク | コマンド | 説明 |
+|--------|---------|------|
+| `build` | `stack build` | プロジェクトのビルド |
+| `test` | `stack test` | HSpec テストスイートの実行 |
+| `lint` | `hlint src/ test/ app/` | HLint による静的解析 |
+| `complexity` | `bash scripts/complexity.sh` | 循環複雑度チェック |
+| `check` | `lint` + `complexity` + `test` | 品質ゲートの一括実行 |
+| `clean` | `stack clean` | ビルド成果物の削除 |
+
+この構成の狙いは、`make check` 1 つで品質ゲートをまとめて実行できる点です。
+
+### タスクの実行
+
+Nix 環境内で実行するのが前提です。
+
+```bash
+# Nix 環境に入ってから実行
+nix develop .#haskell
+cd apps/haskell
+make check
+
+# または Nix 環境外からワンライナーで実行
+nix develop .#haskell --command bash -c "cd apps/haskell && make check"
+```
+
+`make check` の実行順序は次の通りです。
+
+1. **lint** -- HLint がコードスタイルと潜在的問題をチェック
+2. **complexity** -- カスタムスクリプトが循環複雑度を検証
+3. **test** -- HSpec がテストスイートを実行
+
+いずれかのステップが失敗すると、以降のステップは実行されません。
+
+### Stack の監視実行
+
+Stack には `--file-watch` オプションがあり、ファイル変更を監視して自動的にテストを再実行できます。
+
+```bash
+stack test --file-watch
+```
+
+TDD の Red → Green を高速に回すときに有効です。ファイルを保存するたびにテストが自動実行されるため、即座にフィードバックを得られます。
+
+## 6.4 GitHub Actions による CI/CD
+
+`.github/workflows/haskell-ci.yml` では、Nix を活用して CI を実行しています。
+
+```yaml
+name: Haskell CI
+
+on:
+  push:
+    paths:
+      - "apps/haskell/**"
+      - ".github/workflows/haskell-ci.yml"
+  pull_request:
+    paths:
+      - "apps/haskell/**"
+      - ".github/workflows/haskell-ci.yml"
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: cachix/install-nix-action@v30
+        with:
+          nix_path: nixpkgs=channel:nixos-unstable
+
+      - name: Cache Nix store
+        uses: actions/cache@v4
+        with:
+          path: /tmp/nix-cache
+          key: ${{ runner.os }}-nix-haskell-${{ hashFiles('flake.lock', 'ops/nix/environments/haskell/shell.nix') }}
+          restore-keys: |
+            ${{ runner.os }}-nix-haskell-
+
+      - name: Cache Stack
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.stack
+            apps/haskell/.stack-work
+          key: ${{ runner.os }}-stack-${{ hashFiles('apps/haskell/stack.yaml', 'apps/haskell/package.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-stack-
+
+      - name: Build dependencies
+        run: nix develop .#haskell --command bash -c "cd apps/haskell && stack build --only-dependencies --test --no-run-tests"
+
+      - name: Lint (HLint)
+        run: nix develop .#haskell --command bash -c "cd apps/haskell && hlint src/ test/ app/"
+
+      - name: Complexity check
+        run: nix develop .#haskell --command bash -c "cd apps/haskell && bash scripts/complexity.sh --threshold 10 src"
+
+      - name: Test
+        run: nix develop .#haskell --command bash -c "cd apps/haskell && stack test"
+```
+
+### ワークフローの構成
+
+CI パイプラインは次の 4 ステップで構成されています。
+
+| ステップ | 内容 |
+|---------|------|
+| Build dependencies | 依存パッケージのビルド（テスト実行なし） |
+| Lint (HLint) | 静的解析による品質チェック |
+| Complexity check | 循環複雑度の検証 |
+| Test | HSpec テストスイートの実行 |
+
+### トリガー条件
+
+```yaml
+on:
+  push:
+    paths:
+      - "apps/haskell/**"
+      - ".github/workflows/haskell-ci.yml"
+  pull_request:
+    paths:
+      - "apps/haskell/**"
+      - ".github/workflows/haskell-ci.yml"
+```
+
+`paths` フィルタにより、Haskell 関連ファイルまたはワークフロー定義に変更があった場合のみ CI が実行されます。他の言語のコード変更では実行されないため、CI リソースを節約できます。
+
+### キャッシュ戦略
+
+CI では 2 種類のキャッシュを使用しています。
+
+**Nix ストアキャッシュ**
+
+```yaml
+- name: Cache Nix store
+  uses: actions/cache@v4
+  with:
+    path: /tmp/nix-cache
+    key: ${{ runner.os }}-nix-haskell-${{ hashFiles('flake.lock', 'ops/nix/environments/haskell/shell.nix') }}
+```
+
+`flake.lock` と `shell.nix` のハッシュをキーにすることで、Nix 環境が変わらない限りキャッシュが再利用されます。
+
+**Stack キャッシュ**
+
+```yaml
+- name: Cache Stack
+  uses: actions/cache@v4
+  with:
+    path: |
+      ~/.stack
+      apps/haskell/.stack-work
+    key: ${{ runner.os }}-stack-${{ hashFiles('apps/haskell/stack.yaml', 'apps/haskell/package.yaml') }}
+```
+
+`stack.yaml` と `package.yaml` のハッシュをキーにすることで、依存関係が変わらない限りビルド済みパッケージが再利用されます。`~/.stack` にはグローバルなパッケージデータベース、`apps/haskell/.stack-work` にはプロジェクト固有のビルド成果物が保存されます。
+
+### Nix を CI で使う利点
+
+- **環境の再現性**: ローカルと CI で同じ Nix 環境を使うため、環境差異による失敗がない
+- **ツールバージョンの固定**: `flake.lock` でパッケージバージョンが固定される
+- **キャッシュの効率化**: `flake.lock` と `shell.nix` のハッシュでキャッシュキーを生成し、変更時のみ再構築
+- **統一的なパターン**: Scala、Clojure など他の言語と同じ CI パターンを使える
+
+## 6.5 品質ゲートの統合
+
+`make check` は、ローカル開発と CI の両方で使える品質ゲートです。
+
+```makefile
+check: lint complexity test
+```
+
+この構成により、以下の品質基準を自動的に検証します。
+
+| チェック | ツール | 基準 |
+|---------|--------|------|
+| 静的解析 | HLint | コードスタイルの指摘がゼロ |
+| 複雑度 | complexity.sh | 全関数が閾値 10 以下 |
+| テスト | HSpec | 全テストが通過 |
+
+ローカルで `make check` を通してからプッシュすることで、CI での失敗を事前に防げます。
+
+## 6.6 開発ワークフロー
+
+Red-Green-Refactor を自動化で支える基本フローは次の通りです。
+
+1. **環境起動**: `nix develop .#haskell` で開発環境に入る
+2. **Red**: 失敗するテストを追加し、`make test` で失敗を確認
+3. **Green**: 最小実装で `make test` を通過
+4. **Refactor**: `make check` で静的解析・複雑度・テストを一括確認
+5. **Push**: GitHub Actions で Nix 環境内の同じチェックを再実行
+
+ローカルと CI で同じ Nix 環境・同じコマンドを使うことで、環境差分による失敗を防げます。
+
+```bash
+# 典型的な開発セッション
+nix develop .#haskell
+cd apps/haskell
+
+# ファイル監視モードでテスト
+stack test --file-watch
+
+# （別ターミナルで）コードを編集 → 自動でテスト実行
+
+# プッシュ前に品質ゲートを通す
+make check
+
+# コミットしてプッシュ
+git add src/FizzBuzz.hs test/FizzBuzz/FizzBuzzSpec.hs
+git commit -m "feat(fizzbuzz): generateList を実装"
+git push
+```
+
+## 6.7 まとめ
+
+この章では、Haskell 開発の自動化基盤を整理しました。
+
+- Nix Flakes で GHC、Stack、HLint を含む開発環境を宣言的に管理し、再現性を確保する
+- Makefile で日常タスク（`build`, `test`, `lint`, `complexity`, `check`, `clean`）を短いコマンドに集約する
+- `make check` で HLint + 複雑度チェック + テストの品質ゲートを一括実行する
+- GitHub Actions で Nix 環境を使い、ローカルと同一の品質ゲートを適用する
+- Stack キャッシュと Nix キャッシュで CI の実行時間を短縮する
+
+第 2 部の環境整備が完了したので、次章からは型クラスと代数的データ型に進みます。