@k2works/claude-code-booster 3.0.0 → 3.1.0

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

@@ -0,0 +1,321 @@
+# 第 6 章: タスクランナーと CI/CD
+
+## 6.1 はじめに
+
+前章では静的コード解析ツールとコードカバレッジを導入しました。テストの実行、静的解析、フォーマットチェック、カバレッジ計測と、様々なコマンドを使えるようになりましたが、毎回それぞれのコマンドを覚えて実行するのは面倒です。
+
+この章では **タスクランナー** を使ってこれらのタスクをまとめて実行できるようにし、さらに **CI/CD** パイプラインを構築します。
+
+## 6.2 Composer scripts によるタスク管理
+
+### Composer scripts とは
+
+> Composer scripts は composer.json に定義するタスクランナー機能です。定型的なコマンドをスクリプトとして登録し、`composer <スクリプト名>` で実行できます。
+
+Ruby の Rake、Java の Gradle タスク、Node の npm scripts、Python の tox、Go の Makefile に相当します。
+
+### スクリプトの定義
+
+`composer.json` に scripts セクションを追加します。
+
+```json
+{
+    "scripts": {
+        "test": "vendor/bin/phpunit",
+        "test:coverage": "vendor/bin/phpunit --coverage-text",
+        "lint": "vendor/bin/phpcs",
+        "lint:fix": "vendor/bin/phpcbf",
+        "analyse": "vendor/bin/phpstan analyse",
+        "check": [
+            "@lint",
+            "@analyse",
+            "@test"
+        ]
+    }
+}
+```
+
+### 主要スクリプトの解説
+
+| スクリプト | 説明 | 実行コマンド |
+|-----------|------|-------------|
+| `composer test` | PHPUnit テストを実行 | `vendor/bin/phpunit` |
+| `composer test:coverage` | テスト + カバレッジ | `vendor/bin/phpunit --coverage-text` |
+| `composer lint` | コーディング規約チェック | `vendor/bin/phpcs` |
+| `composer lint:fix` | コーディング規約の自動修正 | `vendor/bin/phpcbf` |
+| `composer analyse` | PHPStan 静的解析 | `vendor/bin/phpstan analyse` |
+| `composer check` | 全品質チェックを一括実行 | lint + analyse + test |
+
+### タスクの実行
+
+```bash
+# テスト実行
+$ composer test
+> vendor/bin/phpunit
+PHPUnit 10.5.x by Sebastian Bergmann and contributors.
+
+Runtime:       PHP 8.4.x
+
+..........                                                        10 / 10 (100%)
+
+Time: 00:00.xxx, Memory: x.xx MB
+
+OK (10 tests, 18 assertions)
+
+# 全品質チェック
+$ composer check
+> vendor/bin/phpcs
+> vendor/bin/phpstan analyse
+
+ [OK] No errors
+
+> vendor/bin/phpunit
+
+OK (10 tests, 18 assertions)
+```
+
+`check` スクリプトは `@lint`、`@analyse`、`@test` を順に実行します。`@` プレフィックスは他のスクリプトを参照する Composer の構文です。いずれかが失敗した時点で実行は中断されます。
+
+## 6.3 Makefile による補助
+
+Composer scripts をさらにラップして、開発チーム全体で統一的なインターフェースを提供するために Makefile を使うこともできます。
+
+```makefile
+.PHONY: test lint analyse check coverage setup
+
+test: ## テストを実行
+	composer test
+
+lint: ## コーディング規約チェック
+	composer lint
+
+lint-fix: ## コーディング規約を自動修正
+	composer lint:fix
+
+analyse: ## PHPStan 静的解析
+	composer analyse
+
+check: ## 全品質チェック（lint + analyse + test）
+	composer check
+
+coverage: ## テスト + カバレッジ
+	composer test:coverage
+
+setup: ## 初期セットアップ
+	composer install
+```
+
+```bash
+# ヘルプ表示
+$ make help
+
+# 全品質チェック
+$ make check
+```
+
+## 6.4 CI/CD パイプライン
+
+### GitHub Actions とは
+
+> GitHub Actions は GitHub に組み込まれた CI/CD プラットフォームです。リポジトリへのプッシュやプルリクエスト作成をトリガーに、テストやデプロイを自動実行できます。
+
+### ワークフロー定義
+
+`.github/workflows/php.yml` を作成します。
+
+```yaml
+name: PHP CI
+
+on:
+  push:
+    branches: [ main, develop ]
+    paths:
+      - 'apps/php/**'
+  pull_request:
+    branches: [ main ]
+    paths:
+      - 'apps/php/**'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: apps/php
+
+    strategy:
+      matrix:
+        php-version: ['8.1', '8.2', '8.3', '8.4']
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup PHP ${{ matrix.php-version }}
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php-version }}
+          extensions: mbstring, xml
+          coverage: xdebug
+
+      - name: Install dependencies
+        run: composer install --no-interaction --prefer-dist
+
+      - name: Run coding standard check
+        run: composer lint
+
+      - name: Run static analysis
+        run: composer analyse
+
+      - name: Run tests
+        run: composer test
+
+      - name: Run tests with coverage
+        if: matrix.php-version == '8.4'
+        run: composer test:coverage
+```
+
+### ワークフローの解説
+
+```plantuml
+@startuml
+title GitHub Actions ワークフロー
+
+|GitHub|
+start
+:Push / Pull Request;
+
+|CI Runner|
+:PHP セットアップ;
+note right
+  PHP 8.1, 8.2, 8.3, 8.4
+  の各バージョンで実行
+end note
+
+:composer install;
+:composer lint;
+note right
+  PHP_CodeSniffer
+  PSR-12 チェック
+end note
+
+:composer analyse;
+note right
+  PHPStan
+  静的型解析
+end note
+
+:composer test;
+note right
+  PHPUnit
+  テスト実行
+end note
+
+if (PHP 8.4?) then (yes)
+  :composer test:coverage;
+  note right
+    カバレッジ計測
+  end note
+endif
+
+|GitHub|
+if (全ステップ成功?) then (yes)
+  :✅ CI パス;
+else (no)
+  :❌ CI 失敗;
+endif
+
+stop
+@enduml
+```
+
+### マトリクスビルド
+
+`strategy.matrix` により、PHP 8.1〜8.4 の各バージョンで並列にテストが実行されます。これにより、PHP のバージョン互換性を自動的に検証できます。
+
+| PHP バージョン | 主な特徴 |
+|--------------|---------|
+| 8.1 | readonly プロパティ、enum、Fibers |
+| 8.2 | readonly クラス、DNF 型 |
+| 8.3 | 型付きクラス定数、`json_validate()` |
+| 8.4 | プロパティフック、非対称可視性 |
+
+### CI パイプラインのステップ
+
+| ステップ | 対応するローカルコマンド | 目的 |
+|---------|------------------------|------|
+| Install dependencies | `composer install` | 依存パッケージの導入 |
+| Coding standard check | `composer lint` | PSR-12 準拠の確認 |
+| Static analysis | `composer analyse` | 型エラーの検出 |
+| Run tests | `composer test` | 機能の正しさを検証 |
+| Coverage | `composer test:coverage` | テストカバレッジの計測 |
+
+## 6.5 開発ワークフローのまとめ
+
+三種の神器が揃ったことで、以下の開発ワークフローが確立されました。
+
+```plantuml
+@startuml
+title ソフトウェア開発の三種の神器
+
+rectangle "バージョン管理" as vc #LightBlue {
+  card "Git" as git
+  card "Conventional Commits" as cc
+}
+
+rectangle "テスティング" as testing #LightGreen {
+  card "PHPUnit" as phpunit
+  card "TDD サイクル" as tdd
+}
+
+rectangle "自動化" as automation #LightCoral {
+  card "Composer scripts" as scripts
+  card "GitHub Actions" as gha
+  card "PHP_CodeSniffer" as phpcs
+  card "PHPStan" as phpstan
+}
+
+vc -[hidden]right-> testing
+testing -[hidden]right-> automation
+
+@enduml
+```
+
+### 日常の開発フロー
+
+```bash
+# 1. 開発開始
+$ nix develop .#php
+$ cd apps/php
+
+# 2. TDD サイクル
+#    Red → Green → Refactor
+
+# 3. 品質チェック
+$ composer check
+
+# 4. コミット
+$ git commit -m 'feat: 新機能を追加'
+
+# 5. プッシュ → CI が自動実行
+$ git push
+```
+
+## 6.6 まとめ
+
+この章では以下を構築しました。
+
+| 項目 | ツール | 設定ファイル |
+|------|--------|-------------|
+| タスクランナー | Composer scripts | `composer.json`（scripts セクション） |
+| 補助タスクランナー | Makefile | `Makefile` |
+| CI/CD | GitHub Actions | `.github/workflows/php.yml` |
+
+これでソフトウェア開発の三種の神器が揃いました。
+
+| 神器 | ツール |
+|------|--------|
+| バージョン管理 | Git + Conventional Commits |
+| テスティング | PHPUnit + TDD |
+| 自動化 | Composer scripts + PHP_CodeSniffer + PHPStan + GitHub Actions |
+
+次章からは第 3 部「オブジェクト指向設計」に入り、FizzBuzz を題材にオブジェクト指向プログラミングの原則を段階的に学んでいきます。

package/lib/assets/docs/article/getting-start-tdd/php/07-encapsulation-and-polymorphism.md

@@ -0,0 +1,372 @@
+# 第 7 章: カプセル化とポリモーフィズム
+
+## 7.1 追加仕様と TODO リスト
+
+第 1 部で作成した FizzBuzz プログラムに、新しい仕様を追加します。
+
+**追加仕様**:
+
+- **タイプ 1**（通常）: 3 の倍数→Fizz、5 の倍数→Buzz、両方の倍数→FizzBuzz、それ以外→数値
+- **タイプ 2**（数値のみ）: 常に数値を返す
+- **タイプ 3**（FizzBuzz のみ）: 3 と 5 両方の倍数→FizzBuzz、それ以外→数値
+
+**TODO リスト**:
+
+- [ ] タイプ 1: 通常の FizzBuzz（既存動作）
+- [ ] タイプ 2: 数値のみを返す
+- [ ] タイプ 3: FizzBuzz のみを返す
+- [ ] カプセル化: private / readonly プロパティで内部状態を隠蔽
+- [ ] ポリモーフィズム: インターフェースでタイプを抽象化
+
+## 7.2 手続き型アプローチ
+
+まず、手続き型で 3 つのタイプを実装します。
+
+### テスト
+
+```php
+public function test_タイプ1_数を文字列に変換する(): void
+{
+    $result = basicGenerate(1, 1);
+    $this->assertSame('1', $result);
+}
+
+public function test_タイプ1_3の倍数でFizzを返す(): void
+{
+    $result = basicGenerate(3, 1);
+    $this->assertSame('Fizz', $result);
+}
+
+public function test_タイプ2_数を文字列に変換する(): void
+{
+    $result = basicGenerate(3, 2);
+    $this->assertSame('3', $result);
+}
+
+public function test_タイプ3_FizzBuzzのみ返す(): void
+{
+    $result = basicGenerate(15, 3);
+    $this->assertSame('FizzBuzz', $result);
+}
+
+public function test_タイプ3_FizzBuzz以外は数値を返す(): void
+{
+    $result = basicGenerate(3, 3);
+    $this->assertSame('3', $result);
+}
+```
+
+### 実装
+
+<details>
+<summary>手続き型の実装</summary>
+
+```php
+function basicGenerate(int $number, int $type): string
+{
+    $isFizz = $number % 3 === 0;
+    $isBuzz = $number % 5 === 0;
+
+    switch ($type) {
+        case 1:
+            if ($isFizz && $isBuzz) {
+                return 'FizzBuzz';
+            }
+            if ($isFizz) {
+                return 'Fizz';
+            }
+            if ($isBuzz) {
+                return 'Buzz';
+            }
+            return (string) $number;
+        case 2:
+            return (string) $number;
+        case 3:
+            if ($isFizz && $isBuzz) {
+                return 'FizzBuzz';
+            }
+            return (string) $number;
+        default:
+            throw new \InvalidArgumentException("該当するタイプは存在しません");
+    }
+}
+```
+
+</details>
+
+この実装には問題があります:
+
+- **switch 文の肥大化**: タイプが増えるたびに分岐が増える
+- **変更の影響範囲が広い**: 1 つのタイプを変更すると関数全体に影響
+- **テストが複雑化**: すべてのタイプが 1 つの関数に集約されている
+
+## 7.3 カプセル化: private と readonly
+
+PHP では **アクセス修飾子**（`private` / `protected` / `public`）と **readonly プロパティ**（PHP 8.1+）でカプセル化を実現します。
+
+### アクセス修飾子
+
+| 修飾子 | アクセス範囲 |
+|--------|------------|
+| `public` | どこからでもアクセス可能 |
+| `protected` | 自クラスとサブクラスからのみ |
+| `private` | 自クラス内のみ |
+
+### readonly プロパティ（PHP 8.1+）
+
+```php
+class FizzBuzzValue
+{
+    public function __construct(
+        private readonly int $number,
+        private readonly string $value,
+    ) {
+    }
+
+    public function getNumber(): int
+    {
+        return $this->number;
+    }
+
+    public function getValue(): string
+    {
+        return $this->value;
+    }
+}
+```
+
+**コンストラクタプロモーション**（PHP 8.0+）と **readonly**（PHP 8.1+）を組み合わせることで:
+
+1. **プロパティ宣言とコンストラクタ代入を 1 行で記述**
+2. **一度設定した値を変更不可に**（イミュータブル）
+
+### 他言語との比較
+
+| 言語 | カプセル化の手段 |
+|------|----------------|
+| PHP | `private` / `protected` / `public` + `readonly`（8.1+） |
+| Java | `private` / `protected` / `public` + `final` |
+| Go | 大文字/小文字の命名規約 |
+| Ruby | `private` / `protected` / `public` メソッド |
+| TypeScript | `private` / `protected` / `public` 修飾子 |
+| Python | `_` プレフィックス（慣例） |
+
+## 7.4 ポリモーフィズム: インターフェース
+
+PHP のインターフェースは **明示的実装** です。`implements` キーワードでインターフェースの実装を宣言します。
+
+### インターフェース定義
+
+```php
+interface FizzBuzzType
+{
+    public function generate(int $number): FizzBuzzValue;
+}
+```
+
+### タイプ別の実装
+
+```php
+class FizzBuzzType01 implements FizzBuzzType
+{
+    public function generate(int $number): FizzBuzzValue
+    {
+        if ($number % 3 === 0 && $number % 5 === 0) {
+            return new FizzBuzzValue($number, 'FizzBuzz');
+        }
+        if ($number % 3 === 0) {
+            return new FizzBuzzValue($number, 'Fizz');
+        }
+        if ($number % 5 === 0) {
+            return new FizzBuzzValue($number, 'Buzz');
+        }
+
+        return new FizzBuzzValue($number, (string) $number);
+    }
+}
+
+class FizzBuzzType02 implements FizzBuzzType
+{
+    public function generate(int $number): FizzBuzzValue
+    {
+        return new FizzBuzzValue($number, (string) $number);
+    }
+}
+
+class FizzBuzzType03 implements FizzBuzzType
+{
+    public function generate(int $number): FizzBuzzValue
+    {
+        if ($number % 3 === 0 && $number % 5 === 0) {
+            return new FizzBuzzValue($number, 'FizzBuzz');
+        }
+
+        return new FizzBuzzValue($number, (string) $number);
+    }
+}
+```
+
+### テスト
+
+```php
+public function test_タイプ1_数を文字列に変換する(): void
+{
+    $type = new FizzBuzzType01();
+    $result = $type->generate(1);
+    $this->assertSame('1', $result->getValue());
+}
+
+public function test_タイプ1_3の倍数でFizzを返す(): void
+{
+    $type = new FizzBuzzType01();
+    $result = $type->generate(3);
+    $this->assertSame('Fizz', $result->getValue());
+}
+
+public function test_タイプ2_常に数値を返す(): void
+{
+    $type = new FizzBuzzType02();
+    $result = $type->generate(3);
+    $this->assertSame('3', $result->getValue());
+}
+
+public function test_タイプ3_FizzBuzzのみ返す(): void
+{
+    $type = new FizzBuzzType03();
+    $result = $type->generate(15);
+    $this->assertSame('FizzBuzz', $result->getValue());
+}
+
+public function test_タイプ3_FizzBuzz以外は数値を返す(): void
+{
+    $type = new FizzBuzzType03();
+    $result = $type->generate(3);
+    $this->assertSame('3', $result->getValue());
+}
+```
+
+## 7.5 Strategy パターン
+
+ここまでの設計は **Strategy パターン** の適用です。
+
+```plantuml
+@startuml
+title Strategy パターン — FizzBuzz タイプ
+
+interface FizzBuzzType {
+    +generate(number: int): FizzBuzzValue
+}
+
+class FizzBuzzType01 {
+    +generate(number: int): FizzBuzzValue
+}
+
+class FizzBuzzType02 {
+    +generate(number: int): FizzBuzzValue
+}
+
+class FizzBuzzType03 {
+    +generate(number: int): FizzBuzzValue
+}
+
+FizzBuzzType <|.. FizzBuzzType01
+FizzBuzzType <|.. FizzBuzzType02
+FizzBuzzType <|.. FizzBuzzType03
+
+note right of FizzBuzzType
+  PHP のインターフェースは
+  implements で明示的に実装
+end note
+
+@enduml
+```
+
+### Go との比較
+
+| Go（暗黙的実装） | PHP（明示的実装） |
+|-----------------|-----------------|
+| メソッドセット一致で自動実装 | `implements` キーワードが必須 |
+| `type FizzBuzzType01 struct{}` | `class FizzBuzzType01 implements FizzBuzzType` |
+| 構造体埋め込みでコード共有 | trait / abstract class でコード共有 |
+| コンパイル時に型チェック | PHPStan + 実行時にチェック |
+
+## 7.6 ファクトリメソッド
+
+タイプ番号から適切な `FizzBuzzType` を生成するファクトリ関数を用意します。
+
+```php
+class FizzBuzz
+{
+    public static function create(int $type): FizzBuzzType
+    {
+        return match ($type) {
+            1 => new FizzBuzzType01(),
+            2 => new FizzBuzzType02(),
+            3 => new FizzBuzzType03(),
+            default => throw new \InvalidArgumentException(
+                "タイプ{$type}は見つかりません"
+            ),
+        };
+    }
+}
+```
+
+### テスト
+
+```php
+public function test_ファクトリメソッドでタイプ1を生成する(): void
+{
+    $type = FizzBuzz::create(1);
+    $result = $type->generate(3);
+    $this->assertSame('Fizz', $result->getValue());
+}
+
+public function test_不正なタイプで例外を発生する(): void
+{
+    $this->expectException(\InvalidArgumentException::class);
+    FizzBuzz::create(99);
+}
+```
+
+## 7.7 既存コードとの統合
+
+ポリモーフィズムを導入した後、既存の `generate` / `generateList` / `printFizzBuzz` メソッドはタイプ 1 のラッパーとして維持します。
+
+```php
+class FizzBuzz
+{
+    public function generate(int $number): string
+    {
+        $type = new FizzBuzzType01();
+        return $type->generate($number)->getValue();
+    }
+}
+```
+
+これにより、既存のテストはすべてそのまま通ります。
+
+## 7.8 まとめ
+
+第 7 章で達成したこと:
+
+- [x] タイプ 1, 2, 3 の仕様を追加
+- [x] 手続き型（switch 文）の問題点を確認
+- [x] private / readonly プロパティによるカプセル化
+- [x] コンストラクタプロモーション（PHP 8.0+）の活用
+- [x] インターフェースによるポリモーフィズム
+- [x] Strategy パターンの適用
+- [x] ファクトリメソッド（match 式）でインスタンス生成
+- [x] 既存コードとの後方互換性を維持
+
+### TDD サイクルの実践
+
+```plantuml
+@startuml
+:Red: basicGenerate のテスト作成;
+:Green: switch 文で仮実装;
+:Refactor: インターフェース + クラスに分離;
+:Red: タイプ別テスト作成;
+:Green: 各タイプの generate 実装;
+:Refactor: ファクトリメソッドを追加;
+@enduml
+```