@k2works/claude-code-booster 2.7.1 → 3.1.0

package/lib/assets/docs/article/getting-start-tdd/node/12-error-handling-and-type-safety.md

@@ -0,0 +1,295 @@
+# 第 12 章: エラーハンドリングと型安全性
+
+## 12.1 はじめに
+
+前章までに関数型のコレクション操作とパイプライン処理を学びました。この最終章では、TypeScript の型システムを活用した **型安全なエラーハンドリング** を実装します。
+
+## 12.2 現在の問題点
+
+### 数値ベースのファクトリメソッド
+
+```typescript
+// 現在の実装: 数値で型を指定
+static create(type: number = FizzBuzzType.TYPE_01): FizzBuzzType {
+  switch (type) {
+    case FizzBuzzType.TYPE_01: return new FizzBuzzType01();
+    // ...
+    default: throw new Error(`未定義のタイプ: ${type}`);
+  }
+}
+```
+
+**問題点**:
+
+- `number` 型は任意の数値を受け付ける（型安全でない）
+- 無効な値を渡すとランタイムエラーが発生
+- コンパイル時にミスを検出できない
+
+## 12.3 FizzBuzzTypeName enum
+
+### 型安全な列挙型
+
+```typescript
+export enum FizzBuzzTypeName {
+  TYPE_01 = "TYPE_01",
+  TYPE_02 = "TYPE_02",
+  TYPE_03 = "TYPE_03",
+}
+```
+
+### 型安全なファクトリメソッド
+
+`tryCreate` は例外を投げず、`undefined` を返すことで安全にエラーを表現します。
+
+```typescript
+static tryCreate(typeName: FizzBuzzTypeName): FizzBuzzType | undefined {
+  const typeMap: Record<FizzBuzzTypeName, () => FizzBuzzType> = {
+    [FizzBuzzTypeName.TYPE_01]: () => new FizzBuzzType01(),
+    [FizzBuzzTypeName.TYPE_02]: () => new FizzBuzzType02(),
+    [FizzBuzzTypeName.TYPE_03]: () => new FizzBuzzType03(),
+  };
+  return typeMap[typeName]?.();
+}
+```
+
+**利点**:
+
+| 観点 | `create(number)` | `tryCreate(FizzBuzzTypeName)` |
+|------|-----------------|------------------------------|
+| **型安全性** | 任意の数値を受容 | enum 値のみ受容 |
+| **エラー処理** | 例外を throw | `undefined` を返却 |
+| **コンパイル時チェック** | なし | 不正な値はコンパイルエラー |
+| **拡張時** | switch 文を修正 | `Record` に追加 |
+
+### テスト
+
+```typescript
+describe("型安全なファクトリメソッド", () => {
+  test("FizzBuzzTypeName.TYPE_01 を指定すると FizzBuzzType01 が返る", () => {
+    const type = FizzBuzzType.tryCreate(FizzBuzzTypeName.TYPE_01);
+    expect(type).toBeInstanceOf(FizzBuzzType01);
+  });
+
+  test("FizzBuzzTypeName.TYPE_02 を指定すると FizzBuzzType02 が返る", () => {
+    const type = FizzBuzzType.tryCreate(FizzBuzzTypeName.TYPE_02);
+    expect(type).toBeInstanceOf(FizzBuzzType02);
+  });
+
+  test("FizzBuzzTypeName.TYPE_03 を指定すると FizzBuzzType03 が返る", () => {
+    const type = FizzBuzzType.tryCreate(FizzBuzzTypeName.TYPE_03);
+    expect(type).toBeInstanceOf(FizzBuzzType03);
+  });
+});
+```
+
+## 12.4 検索メソッドと Union Types
+
+### FizzBuzzList の検索メソッド
+
+`find` は `FizzBuzzValue | undefined` を返す Union Type で、値が見つからない可能性を型で表現します。
+
+```typescript
+find(
+  predicate: (value: FizzBuzzValue) => boolean,
+): FizzBuzzValue | undefined {
+  return this._list.find(predicate);
+}
+
+some(predicate: (value: FizzBuzzValue) => boolean): boolean {
+  return this._list.some(predicate);
+}
+
+every(predicate: (value: FizzBuzzValue) => boolean): boolean {
+  return this._list.every(predicate);
+}
+```
+
+### Union Type の活用
+
+TypeScript の Union Type（`T | undefined`）は、Java の `Optional<T>` や Python の `T | None` に相当します。
+
+```typescript
+const result = list.find(isFizz);
+if (result !== undefined) {
+  // ここでは result は FizzBuzzValue 型に絞り込まれる
+  console.log(result.value);
+}
+```
+
+### テスト
+
+```typescript
+describe("検索メソッド", () => {
+  const list = FizzBuzzList.generate(
+    FizzBuzzType.create(FizzBuzzType.TYPE_01),
+    15,
+  );
+
+  test("find で条件に合う最初の要素を見つける", () => {
+    const result = list.find((v) => v.value === "Fizz");
+    expect(result?.toString()).toBe("Fizz");
+  });
+
+  test("find で見つからない場合 undefined を返す", () => {
+    const result = list.find((v) => v.value === "NotExist");
+    expect(result).toBeUndefined();
+  });
+
+  test("some で条件に合う要素があるか判定する", () => {
+    expect(list.some((v) => v.value === "Buzz")).toBe(true);
+    expect(list.some((v) => v.value === "NotExist")).toBe(false);
+  });
+
+  test("every で全要素が条件を満たすか判定する", () => {
+    const numberList = FizzBuzzList.generate(
+      FizzBuzzType.create(FizzBuzzType.TYPE_02),
+      5,
+    );
+    expect(numberList.every((v) => !isNaN(Number(v.value)))).toBe(true);
+    expect(list.every((v) => !isNaN(Number(v.value)))).toBe(false);
+  });
+});
+```
+
+## 12.5 Type Guards
+
+### カスタム Type Guard
+
+TypeScript の **Type Guard** 関数で、`unknown` 型から安全に型を絞り込みます。
+
+```typescript
+export function isFizzBuzzValue(value: unknown): value is FizzBuzzValue {
+  return value instanceof FizzBuzzValue;
+}
+
+export function isFizzBuzzList(value: unknown): value is FizzBuzzList {
+  return value instanceof FizzBuzzList;
+}
+```
+
+### 使用例
+
+```typescript
+function processResult(result: unknown): string {
+  if (isFizzBuzzValue(result)) {
+    return result.toString(); // FizzBuzzValue として安全にアクセス
+  }
+  if (isFizzBuzzList(result)) {
+    return result.join(", "); // FizzBuzzList として安全にアクセス
+  }
+  return "unknown";
+}
+```
+
+### テスト
+
+```typescript
+describe("型ガード", () => {
+  test("isFizzBuzzValue は FizzBuzzValue インスタンスで true を返す", () => {
+    expect(isFizzBuzzValue(new FizzBuzzValue("Fizz", 3))).toBe(true);
+  });
+
+  test("isFizzBuzzValue は非インスタンスで false を返す", () => {
+    expect(isFizzBuzzValue("Fizz")).toBe(false);
+    expect(isFizzBuzzValue(null)).toBe(false);
+  });
+});
+```
+
+## 12.6 エントリポイントの更新
+
+```typescript
+// src/index.ts
+export {
+  FizzBuzzValue,
+  FizzBuzzList,
+  FizzBuzzType,
+  FizzBuzzTypeName,
+  FizzBuzzType01,
+  FizzBuzzType02,
+  FizzBuzzType03,
+  isFizzBuzzList,
+  isFizzBuzzValue,
+  FizzBuzzValueCommand,
+  FizzBuzzListCommand,
+} from "./fizzbuzz/index.js";
+```
+
+### テスト実行結果
+
+```
+ ✓ test/fizzbuzz/domain/model/fizz-buzz-value.test.ts (4 tests) 3ms
+ ✓ test/fizzbuzz/application/fizz-buzz-command.test.ts (3 tests) 5ms
+ ✓ test/fizzbuzz/domain/type/fizz-buzz-util.test.ts (8 tests) 5ms
+ ✓ test/fizzbuzz/domain/type/fizz-buzz-type.test.ts (19 tests) 7ms
+ ✓ test/fizzbuzz/domain/model/fizz-buzz-list.test.ts (19 tests) 10ms
+
+ Test Files  5 passed (5)
+      Tests  53 passed (53)
+```
+
+## 12.7 各言語のエラーハンドリング比較
+
+| 概念 | TypeScript | Java | Python |
+|------|-----------|------|--------|
+| Null 安全 | `T \| undefined`、`?` 演算子 | `Optional<T>` | `T \| None`、型ヒント |
+| 列挙型 | `enum` | `enum` | `enum.Enum` |
+| 型ガード | `value is T` 述語 | `instanceof` | `isinstance()` |
+| パターンマッチ | （TC39 提案中） | switch 式 | `match` 文（3.10+） |
+| 型安全ファクトリ | `Record<Enum, () => T>` | switch 式 + enum | `dict[Enum, Callable]` |
+
+## 12.8 第 4 部のまとめ
+
+第 4 部（章 10〜12）を通じて、OOP 設計のコードに関数型プログラミングのパターンを適用しました。
+
+| 章 | テーマ | 適用した概念 |
+|---|--------|-----------|
+| 10 | 高階関数と関数合成 | map/filter/reduce、compose/pipe、述語関数 |
+| 11 | 不変データとパイプライン | groupBy/countBy/take/join、ジェネレータ、構造的型付け |
+| 12 | エラーハンドリングと型安全性 | enum ファクトリ、Union Types、Type Guards |
+
+### 全 12 章の旅
+
+| 部 | 章 | テーマ |
+|---|---|--------|
+| **第 1 部** | 1-3 | TDD の基本サイクル（Red-Green-Refactor） |
+| **第 2 部** | 4-6 | 開発環境と自動化（Git、ESLint、CI/CD） |
+| **第 3 部** | 7-9 | OOP 設計（Strategy、Command、SOLID、モジュール設計） |
+| **第 4 部** | 10-12 | 関数型プログラミング（高階関数、パイプライン、型安全性） |
+
+### 最終的なディレクトリ構成
+
+```
+src/fizzbuzz/
+├── index.ts                          (バレルファイル)
+├── domain/
+│   ├── model/
+│   │   ├── fizz-buzz-value.ts       (値オブジェクト)
+│   │   └── fizz-buzz-list.ts        (ファーストクラスコレクション + FP メソッド)
+│   └── type/
+│       ├── fizz-buzz-type.ts        (抽象クラス + ファクトリ)
+│       ├── fizz-buzz-type-name.ts   (型安全 enum)
+│       ├── fizz-buzz-type-01.ts     (タイプ 1)
+│       ├── fizz-buzz-type-02.ts     (タイプ 2)
+│       ├── fizz-buzz-type-03.ts     (タイプ 3)
+│       └── fizz-buzz-util.ts        (関数合成 + 述語 + Type Guards)
+└── application/
+    ├── fizz-buzz-command.ts         (コマンドインターフェース)
+    ├── fizz-buzz-value-command.ts   (単一値コマンド)
+    └── fizz-buzz-list-command.ts    (リストコマンド)
+
+test/fizzbuzz/
+├── domain/
+│   ├── model/
+│   │   ├── fizz-buzz-value.test.ts  (4 tests)
+│   │   └── fizz-buzz-list.test.ts   (19 tests)
+│   └── type/
+│       ├── fizz-buzz-type.test.ts   (19 tests)
+│       └── fizz-buzz-util.test.ts   (8 tests)
+└── application/
+    └── fizz-buzz-command.test.ts    (3 tests)
+```
+
+**テスト合計: 53 テスト、5 ファイル、全パス**
+
+FizzBuzz という単純な問題を題材に、TDD の基本から OOP 設計、関数型プログラミング、型安全性まで、段階的にソフトウェア設計の本質を学びました。

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

@@ -0,0 +1,56 @@
+# テスト駆動開発から始める TypeScript 入門
+
+TypeScript は JavaScript に静的型付けを加えた言語で、大規模アプリケーション開発における型安全性と開発者体験を向上させます。本シリーズでは、FizzBuzz 問題を題材に TDD（テスト駆動開発）の手法を TypeScript で実践します。
+
+## 特徴
+
+- **静的型付け**: コンパイル時の型チェックによりバグを早期発見
+- **JavaScript との互換性**: 既存の JavaScript コードとシームレスに連携
+- **マルチパラダイム**: オブジェクト指向、関数型を柔軟に組み合わせ可能
+- **豊富な型システム**: ジェネリクス、ユニオン型、型ガードによる表現力
+
+## 開発環境
+
+| ツール | 用途 |
+|--------|------|
+| [Vitest](https://vitest.dev/) | テスティングフレームワーク |
+| [npm](https://www.npmjs.com/) | パッケージマネージャ |
+| [ESLint](https://eslint.org/) | リンター |
+| [Prettier](https://prettier.io/) | フォーマッター |
+| [TypeScript](https://www.typescriptlang.org/) | 静的型チェック（tsc） |
+| [Gulp](https://gulpjs.com/) | タスクランナー |
+| [@vitest/coverage-v8](https://vitest.dev/guide/coverage.html) | コードカバレッジ |
+
+## 章構成
+
+### 第 1 部: TDD の基本サイクル
+
+| 章 | テーマ |
+|----|--------|
+| [第 1 章](01-todo-list-and-first-test.md) | TODO リストと最初のテスト |
+| [第 2 章](02-fake-it-and-triangulation.md) | 仮実装と三角測量 |
+| [第 3 章](03-obvious-implementation-and-refactoring.md) | 明白な実装とリファクタリング |
+
+### 第 2 部: 開発環境と自動化
+
+| 章 | テーマ |
+|----|--------|
+| [第 4 章](04-version-control-and-conventional-commits.md) | バージョン管理と Conventional Commits |
+| [第 5 章](05-package-management-and-static-analysis.md) | パッケージ管理と静的解析 |
+| [第 6 章](06-task-runner-and-ci-cd.md) | タスクランナーと CI/CD |
+
+### 第 3 部: オブジェクト指向設計
+
+| 章 | テーマ |
+|----|--------|
+| [第 7 章](07-encapsulation-and-polymorphism.md) | カプセル化とポリモーフィズム |
+| [第 8 章](08-design-patterns.md) | デザインパターンの適用 |
+| [第 9 章](09-solid-principles-and-module-design.md) | SOLID 原則とモジュール設計 |
+
+### 第 4 部: 関数型プログラミングへの展開
+
+| 章 | テーマ |
+|----|--------|
+| [第 10 章](10-higher-order-functions-and-composition.md) | 高階関数と関数合成 |
+| [第 11 章](11-immutable-data-and-pipeline.md) | 不変データとパイプライン処理 |
+| [第 12 章](12-error-handling-and-type-safety.md) | エラーハンドリングと型安全性 |

package/lib/assets/docs/article/getting-start-tdd/php/01-todo-list-and-first-test.md

@@ -0,0 +1,259 @@
+# 第 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 テスティングフレームワークの導入
+
+### テストファースト
+
+最初にプログラムする対象を決めたので、早速プロダクトコードを実装……ではなく **テストファースト** で作業を進めましょう。
+
+> テストファースト
+>
+> いつテストを書くべきだろうか——それはテスト対象のコードを書く前だ。
+>
+> — テスト駆動開発
+
+今回 PHP のテスティングフレームワークには [PHPUnit](https://phpunit.de/) を利用します。PHPUnit は PHP のデファクトスタンダードなテスティングフレームワークで、Java の JUnit にインスパイアされた xUnit 系のフレームワークです。
+
+### 開発環境のセットアップ
+
+Composer でプロジェクトを初期化し、PHPUnit をインストールします。
+
+```bash
+# プロジェクトの初期化
+$ cd apps/php
+$ composer init --name="fizzbuzz/php-tdd" --type="project" --require="php:^8.1" --no-interaction
+$ composer require --dev phpunit/phpunit
+```
+
+PSR-4 オートロードを設定した `composer.json` を用意します。
+
+```json
+{
+    "autoload": {
+        "psr-4": {
+            "App\\": "src/"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "App\\Tests\\": "tests/"
+        }
+    }
+}
+```
+
+PHPUnit の設定ファイル `phpunit.xml` を作成します。
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
+         bootstrap="vendor/autoload.php"
+         colors="true"
+         testdox="true">
+    <testsuites>
+        <testsuite name="FizzBuzz Tests">
+            <directory>tests</directory>
+        </testsuite>
+    </testsuites>
+</phpunit>
+```
+
+### 環境確認テスト
+
+環境が正しく設定されていることを確認するため、学習用テストを書きます。
+
+```php
+<?php
+// tests/LearningTest.php
+
+namespace App\Tests;
+
+use PHPUnit\Framework\TestCase;
+
+class LearningTest extends TestCase
+{
+    public function test_PHPの文字列キャストを確認する(): void
+    {
+        $this->assertSame('42', (string) 42);
+    }
+
+    public function test_PHPのintval関数を確認する(): void
+    {
+        $this->assertSame(42, intval('42'));
+    }
+}
+```
+
+テストを実行します。
+
+```bash
+$ vendor/bin/phpunit
+OK (2 tests, 2 assertions)
+```
+
+テストが通りました。PHPUnit が正常に動作することが確認できました。PHP では `assertSame` は値と型の両方を比較します（`===` 相当）。Go の `if got != want` パターンや Ruby の `assert_equal` に相当します。
+
+## 1.5 仮実装
+
+テスト環境の準備ができたので、TODO リストの最初の作業に取り掛かりましょう。
+
+**TODO リスト**:
+
+- [ ] 数を文字列にして返す
+  - **1 を渡したら文字列 "1" を返す**
+- [ ] 3 の倍数のときは数の代わりに「Fizz」と返す
+- [ ] 5 の倍数のときは「Buzz」と返す
+- [ ] 3 と 5 両方の倍数の場合には「FizzBuzz」と返す
+- [ ] 1 から 100 までの数
+- [ ] プリントする
+
+まずはアサーションを最初に書きましょう。
+
+> アサートファースト
+>
+> いつアサーションを書くべきだろうか——最初に書こう。
+>
+> — テスト駆動開発
+
+### Red: 最初のテスト
+
+FizzBuzz のテストを書きます。
+
+```php
+<?php
+// tests/FizzBuzzTest.php
+
+namespace App\Tests;
+
+use PHPUnit\Framework\TestCase;
+use App\FizzBuzz;
+
+class FizzBuzzTest extends TestCase
+{
+    public function test_1を渡したら文字列1を返す(): void
+    {
+        $fizzbuzz = new FizzBuzz();
+        $this->assertSame('1', $fizzbuzz->generate(1));
+    }
+}
+```
+
+テストを実行します。
+
+```bash
+$ vendor/bin/phpunit
+Error: Class "App\FizzBuzz" not found
+```
+
+`FizzBuzz` クラスが定義されていないためエラーになりました。PHP は実行時にクラスを解決するため、Go のようなコンパイルエラーではなく実行時エラーになります。
+
+### Green: 仮実装
+
+テストを通すために **仮実装** から始めます。
+
+> 仮実装を経て本実装へ
+>
+> 失敗するテストを書いてから、最初に行う実装はどのようなものだろうか——ベタ書きの値を返そう。
+>
+> — テスト駆動開発
+
+`FizzBuzz` クラスを定義して、文字列リテラルを返します。
+
+```php
+<?php
+// src/FizzBuzz.php
+
+namespace App;
+
+class FizzBuzz
+{
+    public function generate(int $number): string
+    {
+        return '1';
+    }
+}
+```
+
+テストを実行します。
+
+```bash
+$ vendor/bin/phpunit
+FizzBuzz
+ ✔ 1を渡したら文字列1を返す
+
+OK (1 test, 1 assertion)
+```
+
+テストが通りました。こんなベタ書きのプログラムでいいの？と思われるかもしれませんが、この細かいステップに今しばらくお付き合いください。
+
+PHP では `int $number` と `string` の型宣言（Type Declaration）を使うことで、引数と戻り値の型を明示できます。これは Go の静的型付けほど厳密ではありませんが、PHPStan などの静的解析ツールと組み合わせることで型安全性を向上できます。
+
+**TODO リスト**:
+
+- [ ] 数を文字列にして返す
+  - [x] 1 を渡したら文字列 "1" を返す
+- [ ] 3 の倍数のときは数の代わりに「Fizz」と返す
+- [ ] 5 の倍数のときは「Buzz」と返す
+- [ ] 3 と 5 両方の倍数の場合には「FizzBuzz」と返す
+- [ ] 1 から 100 までの数
+- [ ] プリントする
+
+ここまでの作業をバージョン管理システムにコミットしておきましょう。
+
+```bash
+$ git add .
+$ git commit -m 'test: 数を文字列にして返す'
+```
+
+## 1.6 まとめ
+
+この章では以下のことを学びました。
+
+- **TODO リスト** で仕様をプログラミング対象に分解する方法
+- **テストファースト** で最初にテストを書く考え方
+- PHPUnit を使ったテスト実行環境のセットアップ
+- Composer による PSR-4 オートロードの設定
+- **仮実装** でベタ書きの値を返してテストを通す手法
+- **アサートファースト** でテストの終わりから書き始めるアプローチ
+- PHP の型宣言（int, string）による型安全性の向上
+
+次章では、2 つ目のテストケースを追加して **三角測量** を行い、プログラムを一般化していきます。