husky-test-coverage

Husky テストカバレッジ

すべてのコミットでテストが実行され、カバレッジのしきい値が適用されるよう、Husky の git フックを設定または検証します。

契約

入力：

• 対象リポジトリ、セットアップまたは検証モード、カバレッジのしきい値

出力：

• カバレッジのセットアップ計画、適用されたフックや設定の変更、または検証レポート

作成／変更するもの：

• セットアップモードの場合のみ、フック、package スクリプト、依存関係、カバレッジ設定

外部への副作用：

• 許可されたセットアップとホストの制限内での依存関係のインストールおよびテストの実行

確認が必要な事項：

• 検証のリクエストは読み取り専用です。フック、依存関係、しきい値を変更する前に、明示的なセットアップの許可を得てください
• スキルを読み込んでも、追加の権限は付与されません。既存の明示的な承認は、同じ対象と操作にのみ適用されます。レポートのみの制限を維持してください。

委任先：

• なし

使用する場面

• テストカバレッジの適用を初めて設定するとき
• 既存の Husky／テスト設定が正しく構成されているかを検証するとき
• テストカバレッジ用の pre-commit フックを設定するとき
• テストランナーに合わせてカバレッジの設定を調整するとき

プロジェクトコンテキストの確認

1. package.json を確認する：

   • 既存のテストスクリプトを確認する
   • 依存関係からテストランナーを特定する（vitest、mocha）
   • Husky がすでにインストールされているか確認する
   • 既存のカバレッジ設定を確認する

2. テストランナーを特定する：

   • Vitest：依存関係に vitest があるか確認し、vitest.config.ts または vitest.config.js を探します。@vitest/coverage-v8 がインストールされているか確認します
   • Mocha：依存関係に mocha があるか確認し、カバレッジツール（nyc、c8）があるか確認します

3. カバレッジ設定を確認する：

   • Vitest：vitest.config.* 内の test.coverage.thresholds を探します
   • Mocha：.nycrc.json または package.json 内のカバレッジ設定を探します

4. 既存の Husky 設定を検証する：

   • .husky/ ディレクトリが存在するか確認します
   • 既存の pre-commit フックを確認します
   • Husky が package.json の依存関係に含まれているか確認します

5. テストファイルを検出する：

   • *.test.* または *.spec.* ファイルを検索します
   • カバレッジを適用する前に、テストが存在することを確認します

クイックスタート

python3 ${CLAUDE_SKILL_DIR}/scripts/setup-husky-coverage.py --root /path/to/project
python3 ${CLAUDE_SKILL_DIR}/scripts/setup-husky-coverage.py --root /path/to/project --dry-run

しきい値、警告のみ、テストがない場合のスキップの呼び出し例については、references/full-guide.md（§ クイックスタートの例）を参照してください。

設定される内容

Husky のセットアップ

• Husky がまだない場合はインストールします
• Husky を初期化します（bunx husky install）
• テストをカバレッジ付きで実行する .husky/pre-commit フックを作成します
• package.json に prepare スクリプトがなければ追加します

テストランナーの検出

このスキルは次のテストランナーを自動的に検出します。

• Vitest：pre-commit フックで vitest run --coverage を使用します
• Mocha：mocha のテストコマンドとともに nyc または c8 を使用します

カバレッジ設定

Vitest：

• 設定が存在しない場合は、test.coverage.thresholds を含む vitest.config.ts/js を作成します。設定がすでに存在する場合は、スニペットを表示します
• v8 カバレッジプロバイダーを設定し、未インストールの場合は @vitest/coverage-v8 をインストールします
• デフォルトのしきい値：行 80％、分岐 75％、関数 80％、ステートメント 80％

Mocha + nyc：

• カバレッジのしきい値を含む .nycrc.json を作成または更新します
• text、html、lcov レポーターを設定します

Pre-commit フック

作成されるフックは次の処理を行います。

• コミットの前に毎回、カバレッジ付きでテストを実行します
• カバレッジがしきい値を下回る場合、コミットを失敗させます（設定可能）
• テストファイルが見つからない場合はスキップできます（任意）

設定オプション

コマンドライン引数

• --root <path>：プロジェクトのルートディレクトリ（必須）
• --threshold <number>：カバレッジのしきい値（％）（デフォルト：80）
• --fail-on-below：カバレッジがしきい値を下回る場合にコミットを失敗させます（デフォルト：true）
• --no-fail-on-below：カバレッジがしきい値を下回ってもコミットを許可します
• --skip-if-no-tests：テストファイルが見つからない場合、フックをスキップします
• --dry-run：変更を加えずに、実行される内容を表示します

設定ファイル

プロジェクトのルートに .husky-test-coverage.json を作成します。完全なスキーマについては、references/full-guide.md（§ .husky-test-coverage.json の例）を参照してください。

Package.json の設定

代わりに、package.json に追加します。

{
  "huskyTestCoverage": {
    "threshold": 80,
    "failOnBelow": true
  }
}

技術スタックへの適応

Vitest プロジェクト

検出：

• 依存関係に vitest があるか確認します
• vitest.config.ts または vitest.config.js を探します

設定：

• test.coverage.thresholds（プロバイダー v8、パッケージ @vitest/coverage-v8）を含む Vitest 設定を更新または作成します
• pre-commit フック：bunx vitest run --coverage

設定例の全文は、references/full-guide.md（§ Example vitest.config.ts）を参照してください。

Mocha プロジェクト

検出：

• 依存関係に mocha があるか確認します
• カバレッジツール（nyc または c8）があるか確認します

設定：

• nyc 用の .nycrc.json を作成または更新します
• pre-commit フック：nyc --reporter=text --reporter=html bun run test

設定例の全文は、references/full-guide.md（§ Example .nycrc.json）を参照してください。

パッケージマネージャーのサポート

このスキルは、次のパッケージマネージャーを自動検出して使用します。

• bun：bun run test（優先）
• yarn：yarn test
• pnpm：pnpm run test

ワークフロー

1. package.json をスキャンし、テストランナー、依存関係、既存の Husky 設定、カバレッジ設定ファイルを確認します。テストファイルがあることを確認します。
2. Vitest または Mocha を特定し、カバレッジツール（組み込みまたは nyc/c8）を検出して、パッケージマネージャーを特定します。
3. Husky がない場合はインストールし、フックを初期化して、必要に応じて prepare スクリプトを追加します。
4. カバレッジ設定を作成または更新し、しきい値（デフォルトは 80%）を設定して、レポーターを設定します。
5. pre-commit フックスクリプトを生成し、適用方法（ブロックまたは警告）を設定します。
6. セットアップを検証し、コミットでフックをテストして、必要に応じてしきい値を調整します。

他のスキルとの連携

スキル	連携方法
project-init-orchestrator	スキャフォールディング後に自動で呼び出され、Vitest、80% のしきい値、CI/CD を設定します。既存プロジェクトに追加する場合にのみ、このスキルを個別に実行してください。
linter-formatter-init	どちらも Husky を設定します。このスキルはテストカバレッジを担当し、linter-formatter-init はリントとフォーマットを担当します
testing-expert	testing-expert スキルのテストパターンとカバレッジ目標を使用します

手動での連携（既存プロジェクト）

python3 ${CLAUDE_SKILL_DIR}/scripts/setup-husky-coverage.py \
  --root /path/to/project \
  --threshold 80

トラブルシューティング

pre-commit フックが実行されない

# Reinstall Husky
bunx husky install
chmod +x .husky/pre-commit

カバレッジがチェックされない

• テストコマンドにカバレッジフラグが含まれていることを確認します
• カバレッジ設定ファイルが存在し、正しく設定されていることを確認します
• カバレッジツールがインストールされていることを確認します（Vitest の場合は @vitest/coverage-v8、Mocha の場合は nyc/c8）

テストが通過してもフックが失敗する

• カバレッジのしきい値を達成できるか確認します
• カバレッジレポートを確認し、しきい値を下回っている箇所を把握します
• しきい値の調整、またはテストカバレッジの改善を検討します

テストは実行されるが、カバレッジが適用されない

• カバレッジ設定ファイルに正しいしきい値が設定されていることを確認します
• テストランナーがカバレッジに対応していることを確認します（Vitest には @vitest/coverage-v8、Mocha には nyc/c8 が必要です）
• pre-commit フックスクリプトで正しいコマンドが使われていることを確認します

複数のテストランナーが検出された

このスキルは、優先順位に従って最初に検出されたテストランナーを使用します：Vitest > Mocha

リソース

• Husky ドキュメント：https://typicode.github.io/husky/
• Vitest カバレッジ：https://vitest.dev/guide/coverage
• nyc (Istanbul)：https://github.com/istanbuljs/nyc