@k2works/claude-code-booster 2.7.1 → 3.1.0

package/lib/assets/docs/article/getting-start-tdd/node/04-version-control-and-conventional-commits.md

@@ -0,0 +1,112 @@
+# 第 4 章: バージョン管理と Conventional Commits
+
+## 4.1 はじめに
+
+前章までで、TDD の基本サイクルを通じて FizzBuzz プログラムを完成させました。この章からは「動作するきれいなコード」を書き続けるために必要な **ソフトウェア開発の三種の神器** を整備していきます。
+
+> 今日のソフトウェア開発の世界において絶対になければならない 3 つの技術的な柱があります。三本柱と言ったり、三種の神器と言ったりしていますが、それらは
+>
+> - バージョン管理
+> - テスティング
+> - 自動化
+>
+> の 3 つです。
+>
+> — 和田卓人
+
+**バージョン管理** と **テスティング** に関しては第 1 部で触れました。本章ではバージョン管理をさらに深掘りし、**コミットメッセージの規約** について解説します。
+
+## 4.2 コミットメッセージの重要性
+
+これまでの作業では、区切りごとにリポジトリにコミットしてきました。しかし、コミットメッセージの書き方に一貫性がないと、後からプロジェクトの履歴を追うのが難しくなります。
+
+チーム開発では特に、誰がいつ何のためにコードを変更したのかを明確にすることが重要です。そこで役立つのが **Conventional Commits** です。
+
+## 4.3 Conventional Commits
+
+本プロジェクトでは [Angular ルール](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#type) に基づいた **Conventional Commits** の書式を採用します。
+
+### コミットメッセージのフォーマット
+
+```
+<タイプ>(<スコープ>): <タイトル>
+<空行>
+<ボディ>
+<空行>
+<フッタ>
+```
+
+- **ヘッダ** は必須です
+- **スコープ** は任意です
+- タイトルは **50 文字以内** にしてください（GitHub 上で読みやすくなります）
+
+### コミットのタイプ
+
+| タイプ | 説明 | 使用場面 |
+|--------|------|---------|
+| `feat` | A new feature（新しい機能） | 新機能の追加 |
+| `fix` | A bug fix（バグ修正） | バグの修正 |
+| `docs` | Documentation only changes（ドキュメント変更のみ） | README やコメントの更新 |
+| `style` | Changes that do not affect the meaning of the code（コードに影響を与えない変更） | フォーマット、セミコロンの追加など |
+| `refactor` | A code change that neither fixes a bug nor adds a feature（リファクタリング） | コード構造の改善 |
+| `perf` | A code change that improves performance（パフォーマンス改善） | 処理速度の向上 |
+| `test` | Adding missing or correcting existing tests（テストの追加・修正） | テストコードの変更 |
+| `chore` | Changes to the build process or auxiliary tools（ビルドプロセスや補助ツールの変更） | 設定ファイルの更新 |
+
+### コミットメッセージの例
+
+```bash
+# 新機能の追加
+$ git commit -m 'feat: FizzBuzz のリスト生成機能を追加'
+
+# バグ修正
+$ git commit -m 'fix: 15 の倍数の判定ロジックを修正'
+
+# リファクタリング
+$ git commit -m 'refactor: generate メソッドの条件分岐を整理'
+
+# テストの追加
+$ git commit -m 'test: FizzBuzz の境界値テストを追加'
+
+# ビルド設定の変更
+$ git commit -m 'chore: Vitest と TypeScript の設定を更新'
+```
+
+## 4.4 TDD とコミットのタイミング
+
+TDD の Red-Green-Refactor サイクルにおいて、コミットする適切なタイミングは以下の通りです。
+
+```
+Red（テスト作成）→ Green（テスト成功）→ コミット → Refactor（リファクタリング）→ コミット
+```
+
+1. **Green の後** — テストが通った時点でコミット（`feat:` や `fix:`）
+2. **Refactor の後** — リファクタリングが完了しテストがパスした時点でコミット（`refactor:`）
+
+### 実際のコミット例
+
+FizzBuzz の開発過程では、以下のようなコミット履歴になります。
+
+```bash
+$ git log --oneline
+
+abc1234 refactor: generate メソッドの条件順序を最適化
+def5678 feat: 3 と 5 の倍数で FizzBuzz を返す機能を追加
+ghi9012 feat: 5 の倍数で Buzz を返す機能を追加
+jkl3456 feat: 3 の倍数で Fizz を返す機能を追加
+mno7890 feat: 数を文字列に変換する generate メソッドを実装
+pqr1234 test: FizzBuzz の最初のテストを作成
+stu5678 chore: Vitest + TypeScript プロジェクトを初期化
+```
+
+各コミットが小さく、明確な目的を持っていることがわかります。
+
+## 4.5 まとめ
+
+この章では、以下の内容を学びました。
+
+1. **Conventional Commits** — コミットメッセージの統一フォーマット
+2. **コミットのタイプ** — feat、fix、refactor、test、chore などの使い分け
+3. **TDD とコミットのタイミング** — Green 後と Refactor 後にコミット
+
+次の章では、パッケージ管理ツールと静的コード解析を導入し、コードの品質を自動でチェックできるようにします。

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

@@ -0,0 +1,314 @@
+# 第 5 章: パッケージ管理と静的解析
+
+## 5.1 はじめに
+
+前章では Conventional Commits によるコミットメッセージの規約を学びました。この章では、**パッケージ管理** と **静的コード解析** を導入し、コードの品質を自動でチェックできるようにします。
+
+## 5.2 npm によるパッケージ管理
+
+### npm とは
+
+> npm（Node Package Manager）は、Node.js のパッケージマネージャです。`package.json` で依存関係を管理し、プロジェクトのビルドプロセスを自動化できます。
+
+第 1 部で Vitest と TypeScript はすでに導入しています。ここでは、品質管理ツールのための依存関係を追加します。
+
+### package.json の更新
+
+品質管理ツールを追加した `package.json` は以下のようになります。
+
+```json
+{
+  "name": "fizzbuzz",
+  "version": "0.1.0",
+  "description": "FizzBuzz TDD project for Node (JS/TS)",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src/ test/",
+    "lint:fix": "eslint src/ test/ --fix",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\" \"test/**/*.ts\"",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run format:check && npm run lint && npm run typecheck && npm test",
+    "fix": "npm run format && npm run lint:fix",
+    "setup": "npm install && npm run check"
+  },
+  "devDependencies": {
+    "typescript": "^5.7",
+    "@types/node": "^24.0",
+    "vitest": "^3.2",
+    "@vitest/coverage-v8": "^3.2",
+    "eslint": "^9.0",
+    "@typescript-eslint/parser": "^8.0",
+    "@typescript-eslint/eslint-plugin": "^8.0",
+    "eslint-config-prettier": "^10.0",
+    "prettier": "^3.4"
+  }
+}
+```
+
+依存関係をインストールします。
+
+```bash
+$ npm install
+```
+
+### devDependencies の解説
+
+| パッケージ | 用途 |
+|-----------|------|
+| `typescript` | TypeScript コンパイラ |
+| `@types/node` | Node.js の型定義 |
+| `vitest` | テスティングフレームワーク |
+| `@vitest/coverage-v8` | コードカバレッジ（V8 ベース） |
+| `eslint` | 静的コード解析 |
+| `@typescript-eslint/parser` | TypeScript 用 ESLint パーサー |
+| `@typescript-eslint/eslint-plugin` | TypeScript 用 ESLint ルール |
+| `eslint-config-prettier` | ESLint と Prettier の競合回避 |
+| `prettier` | コードフォーマッター |
+
+## 5.3 静的コード解析（ESLint）
+
+### ESLint とは
+
+> ESLint は JavaScript / TypeScript のための静的解析ツールです。コードの問題を自動的に検出し、一部は自動修正できます。
+
+Java の Checkstyle や PMD に相当するツールです。
+
+### eslint.config.mjs の設定
+
+ESLint v9 では **フラットコンフィグ** 形式を使用します。
+
+```javascript
+// eslint.config.mjs
+import tseslint from "@typescript-eslint/eslint-plugin";
+import tsparser from "@typescript-eslint/parser";
+import eslintConfigPrettier from "eslint-config-prettier";
+
+export default [
+  {
+    files: ["src/**/*.ts", "test/**/*.ts"],
+    languageOptions: {
+      parser: tsparser,
+      parserOptions: {
+        ecmaVersion: "latest",
+        sourceType: "module",
+      },
+    },
+    plugins: {
+      "@typescript-eslint": tseslint,
+    },
+    rules: {
+      ...tseslint.configs.recommended.rules,
+      "no-console": "off",
+      "@typescript-eslint/no-unused-vars": "warn",
+      complexity: ["error", { max: 7 }],
+    },
+  },
+  eslintConfigPrettier,
+];
+```
+
+### 循環的複雑度の制限
+
+`complexity: ["error", { max: 7 }]` は **循環的複雑度**（Cyclomatic Complexity）を 7 以下に制限するルールです。
+
+Java の PMD で設定した `CyclomaticComplexity` や Python の Ruff で設定した `max-complexity` と同じ基準です。複雑度が高いメソッドは分割を検討しましょう。
+
+### ESLint の実行
+
+```bash
+# 解析の実行
+$ npx eslint src/ test/
+
+# 自動修正
+$ npx eslint src/ test/ --fix
+```
+
+## 5.4 コードフォーマッター（Prettier）
+
+### Prettier とは
+
+> Prettier はコードフォーマッターです。コードの見た目を統一し、スタイルに関する議論をなくします。
+
+Java の Checkstyle（フォーマットルール）や Python の Ruff（フォーマッター機能）に相当します。
+
+### .prettierrc の設定
+
+```json
+{
+  "semi": true,
+  "trailingComma": "all",
+  "singleQuote": false,
+  "printWidth": 80,
+  "tabWidth": 2
+}
+```
+
+| 設定 | 値 | 説明 |
+|------|-----|------|
+| `semi` | `true` | 文末にセミコロンを付ける |
+| `trailingComma` | `"all"` | 末尾カンマを付ける |
+| `singleQuote` | `false` | ダブルクォートを使用 |
+| `printWidth` | `80` | 1 行の最大文字数 |
+| `tabWidth` | `2` | インデント幅 |
+
+### Prettier の実行
+
+```bash
+# フォーマットチェック
+$ npx prettier --check "src/**/*.ts" "test/**/*.ts"
+
+# 自動フォーマット
+$ npx prettier --write "src/**/*.ts" "test/**/*.ts"
+```
+
+## 5.5 TypeScript コンパイラ（型チェック）
+
+### 型チェックの重要性
+
+TypeScript の大きな利点は **静的型付け** です。`tsc --noEmit` で型チェックのみを実行し、型エラーを早期に検出できます。
+
+Java のコンパイルチェックや Python の mypy に相当します。
+
+### tsconfig.json
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": ".",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*.ts", "test/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+`"strict": true` により、以下の厳格な型チェックが有効になります。
+
+- `strictNullChecks` — null / undefined の厳格なチェック
+- `noImplicitAny` — 暗黙の any を禁止
+- `strictFunctionTypes` — 関数型の厳格なチェック
+
+### 型チェックの実行
+
+```bash
+$ npx tsc --noEmit
+```
+
+## 5.6 コードカバレッジ
+
+### Vitest のカバレッジ機能
+
+Vitest には V8 ベースのカバレッジ機能が組み込まれています。Java の JaCoCo や Python の pytest-cov に相当します。
+
+### vitest.config.ts の設定
+
+```typescript
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    globals: false,
+    environment: "node",
+    include: ["test/**/*.test.ts"],
+    coverage: {
+      provider: "v8",
+      reporter: ["text", "text-summary"],
+      reportsDirectory: "coverage",
+      exclude: [
+        "node_modules/**",
+        "dist/**",
+        "**/*.test.ts",
+        "**/*.config.*",
+        "src/index.ts",
+        "gulpfile.js",
+      ],
+      thresholds: {
+        global: {
+          branches: 80,
+          functions: 80,
+          lines: 80,
+          statements: 80,
+        },
+      },
+    },
+  },
+});
+```
+
+`thresholds` でカバレッジの最低基準を設定しています。80% を下回ると CI が失敗します。
+
+### カバレッジの実行
+
+```bash
+$ npm run test:coverage
+```
+
+```
+ ✓ test/fizzbuzz.test.ts (6 tests) 5ms
+
+ % Coverage report from v8
+-------------|---------|----------|---------|---------|-------------------
+File         | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
+-------------|---------|----------|---------|---------|-------------------
+All files    |   83.33 |      100 |   66.66 |   83.33 |
+ fizzbuzz.ts |   83.33 |      100 |   66.66 |   83.33 | 23-26
+-------------|---------|----------|---------|---------|-------------------
+```
+
+`printFizzBuzz` メソッド（23-26 行目）が未カバーですが、これは学習用テストのため想定通りです。
+
+## 5.7 品質チェックの一括実行
+
+すべての品質チェックを一括で実行する `check` スクリプトを定義しています。
+
+```bash
+$ npm run check
+```
+
+このコマンドは以下を順番に実行します。
+
+1. `format:check` — Prettier のフォーマットチェック
+2. `lint` — ESLint の静的解析
+3. `typecheck` — TypeScript の型チェック
+4. `test` — Vitest のテスト実行
+
+### 各言語の品質ツール比較
+
+| 用途 | TypeScript | Java | Python |
+|------|-----------|------|--------|
+| パッケージ管理 | npm | Gradle | uv |
+| テスト | Vitest | JUnit 5 | pytest |
+| 静的解析 | ESLint | Checkstyle + PMD | Ruff |
+| フォーマッター | Prettier | Checkstyle | Ruff |
+| 型チェック | tsc | javac（暗黙） | mypy |
+| カバレッジ | @vitest/coverage-v8 | JaCoCo | pytest-cov |
+| 複雑度チェック | ESLint complexity | PMD | Ruff McCabe |
+
+## 5.8 まとめ
+
+この章では、以下の品質管理ツールを導入しました。
+
+1. **npm** — パッケージ管理と依存関係の管理
+2. **ESLint** — 静的コード解析（循環的複雑度の制限を含む）
+3. **Prettier** — コードフォーマットの統一
+4. **TypeScript コンパイラ** — 型チェックによるエラーの早期検出
+5. **Vitest カバレッジ** — コードカバレッジの計測（80% 閾値）
+
+次の章では、タスクランナーを導入してこれらの品質チェックを自動化し、CI/CD パイプラインを構築します。

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

@@ -0,0 +1,235 @@
+# 第 6 章: タスクランナーと CI/CD
+
+## 6.1 はじめに
+
+前章では静的コード解析ツールとコードカバレッジを導入しました。テストの実行、静的解析、フォーマットチェック、型チェック、カバレッジ計測と、様々なコマンドを使えるようになりましたが、毎回それぞれのコマンドを覚えて実行するのは面倒です。
+
+この章では **タスクランナー** を使ってこれらのタスクをまとめて実行できるようにし、さらに **CI/CD** パイプラインを構築します。
+
+## 6.2 npm scripts
+
+### npm scripts とは
+
+`package.json` の `scripts` セクションでコマンドを定義し、`npm run <script名>` で実行できます。第 1 部から使ってきた `npm test` も npm scripts の機能です。
+
+### 品質チェックスクリプト
+
+```json
+{
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src/ test/",
+    "lint:fix": "eslint src/ test/ --fix",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\" \"test/**/*.ts\"",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run format:check && npm run lint && npm run typecheck && npm test",
+    "fix": "npm run format && npm run lint:fix"
+  }
+}
+```
+
+### 主要スクリプトの解説
+
+| スクリプト | 説明 |
+|-----------|------|
+| `npm test` | テストを実行 |
+| `npm run test:watch` | ファイル監視モードでテスト実行 |
+| `npm run test:coverage` | テスト実行 + カバレッジレポート |
+| `npm run lint` | ESLint による静的解析 |
+| `npm run format:check` | Prettier のフォーマットチェック |
+| `npm run typecheck` | TypeScript の型チェック |
+| `npm run check` | 全品質チェックを一括実行 |
+| `npm run fix` | フォーマットと ESLint の自動修正 |
+
+`check` スクリプトは `&&` で複数のコマンドを連結しており、前のコマンドが成功した場合のみ次が実行されます。
+
+## 6.3 タスクランナー — Gulp
+
+npm scripts だけでも基本的なタスク管理は可能ですが、**ファイル監視** や **タスクの組み合わせ** をより柔軟に行うために [Gulp](https://gulpjs.com/) を導入します。
+
+Java の Gradle カスタムタスクや Python の tox に相当します。
+
+### Gulp のインストール
+
+```bash
+$ npm install --save-dev gulp gulp-shell
+```
+
+### gulpfile.js の設定
+
+```javascript
+// gulpfile.js
+import { watch, series } from "gulp";
+import shell from "gulp-shell";
+
+// 基本タスク
+export const test = shell.task(["npm run test"]);
+export const coverage = shell.task(["npm run test:coverage"]);
+export const lint = shell.task(["npm run lint"]);
+export const lintFix = shell.task(["npm run lint:fix"]);
+export const format = shell.task(["npm run format"]);
+export const formatCheck = shell.task(["npm run format:check"]);
+export const typecheck = shell.task(["npm run typecheck"]);
+
+// 複合タスク：リント修正 → フォーマット → テスト
+export const checkAndFix = series(lintFix, format, test);
+
+// ファイル監視タスク（Guard 機能）
+export function guard() {
+  console.log("Guard is watching for file changes...");
+  watch("src/**/*.ts", series(lintFix, format, test));
+  watch("test/**/*.ts", series(test));
+}
+
+// デフォルトタスク
+export default series(checkAndFix, guard);
+```
+
+### Gulp タスクの実行
+
+```bash
+# Guard モード（ファイル監視 + 自動テスト）
+$ npm run guard
+
+# 品質チェック + 自動修正
+$ npx gulp checkAndFix
+
+# 個別タスクの実行
+$ npx gulp test
+$ npx gulp lint
+$ npx gulp coverage
+```
+
+### Guard 機能
+
+`guard` タスクはファイルの変更を監視し、変更があるたびに自動でリント、フォーマット、テストを実行します。
+
+- `src/**/*.ts` の変更 → リント修正 → フォーマット → テスト
+- `test/**/*.ts` の変更 → テスト
+
+TDD サイクルでは、Guard を起動した状態でコードを書くと、保存するたびにテストが自動実行され、Red/Green のフィードバックを即座に得られます。
+
+## 6.4 GitHub Actions による CI/CD
+
+プッシュやプルリクエスト時に自動で品質チェックを実行する CI/CD パイプラインを構築します。
+
+### ワークフロー設定
+
+```yaml
+# .github/workflows/node-ci.yml
+name: Node CI
+
+on:
+  push:
+    branches: [main, develop]
+    paths:
+      - "apps/node/**"
+      - ".github/workflows/node-ci.yml"
+  pull_request:
+    branches: [main]
+    paths:
+      - "apps/node/**"
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout the repository
+        uses: actions/checkout@v4
+
+      - name: Install Nix
+        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-node-${{ hashFiles('flake.lock', 'ops/nix/environments/node/shell.nix') }}
+          restore-keys: |
+            ${{ runner.os }}-nix-node-
+
+      - name: Install dependencies
+        run: nix develop .#node --command bash -c "cd apps/node && npm install"
+
+      - name: Run format check
+        run: nix develop .#node --command bash -c "cd apps/node && npm run format:check"
+
+      - name: Run lint
+        run: nix develop .#node --command bash -c "cd apps/node && npm run lint"
+
+      - name: Run type check
+        run: nix develop .#node --command bash -c "cd apps/node && npm run typecheck"
+
+      - name: Run tests
+        run: nix develop .#node --command bash -c "cd apps/node && npm test"
+
+      - name: Run coverage
+        run: nix develop .#node --command bash -c "cd apps/node && npm run test:coverage"
+```
+
+### ワークフローのポイント
+
+| 設定 | 説明 |
+|------|------|
+| `paths` フィルター | `apps/node/**` に変更があった場合のみ実行 |
+| Nix 環境 | `nix develop .#node` で一貫した環境を保証 |
+| キャッシュ | Nix ストアをキャッシュして CI を高速化 |
+| ステップ分離 | 各チェックを個別ステップで実行し、失敗箇所を特定しやすく |
+
+### 各言語の CI/CD 比較
+
+| 項目 | TypeScript | Java | Python |
+|------|-----------|------|--------|
+| CI ツール | GitHub Actions | GitHub Actions | GitHub Actions |
+| 環境管理 | Nix + npm | Nix + Gradle | Nix + uv |
+| テスト | `npm test` | `./gradlew test` | `uv run tox -e test` |
+| 品質チェック | `npm run check` | `./gradlew fullCheck` | `uv run tox` |
+| タスクランナー | Gulp | Gradle | tox |
+
+## 6.5 開発ワークフローのまとめ
+
+ここまでの設定により、以下の開発ワークフローが確立されました。
+
+### 日常の開発フロー
+
+```
+1. Guard を起動（npm run guard）
+2. テストを書く（Red）
+3. 実装する（Green）→ Guard が自動テスト
+4. リファクタリング → Guard が自動テスト
+5. コミット（Conventional Commits）
+6. プッシュ → CI が自動実行
+```
+
+### ツール一覧
+
+| カテゴリ | ツール | 用途 |
+|---------|--------|------|
+| テスト | Vitest | テスト実行 + カバレッジ |
+| パッケージ管理 | npm | 依存関係管理 |
+| 静的解析 | ESLint | コード品質チェック |
+| フォーマッター | Prettier | コードスタイル統一 |
+| 型チェック | TypeScript (tsc) | 静的型チェック |
+| タスクランナー | Gulp | タスク自動化 + ファイル監視 |
+| CI/CD | GitHub Actions | 継続的インテグレーション |
+
+## 6.6 まとめ
+
+第 2 部（章 4〜6）を通じて、ソフトウェア開発の三種の神器を整備しました。
+
+| 神器 | 導入したもの |
+|------|------------|
+| バージョン管理 | Git + Conventional Commits |
+| テスティング | Vitest + TypeScript + カバレッジ |
+| 自動化 | ESLint + Prettier + Gulp + GitHub Actions |
+
+次の第 3 部では、追加仕様を題材にオブジェクト指向設計（カプセル化、ポリモーフィズム、デザインパターン）を学びます。