husky-test-coverage

Husky 测试覆盖率

设置或验证 Husky git 钩子，确保每次提交时都会运行测试并强制执行覆盖率阈值。

约定

输入：

• 目标仓库、设置或验证模式，以及覆盖率阈值

输出：

• 覆盖率设置计划、已应用的钩子／配置更改，或验证报告

创建／修改：

• 仅在设置模式下修改钩子、package 脚本、依赖项和覆盖率配置

外部副作用：

• 在授权的设置范围和主机限制内安装依赖项并运行测试

需要确认：

• 验证请求保持只读。更改钩子、依赖项或阈值前，须获得明确的设置授权
• 加载技能不会授予额外权限。现有的明确批准仅适用于相同的目标和操作；请遵守仅报告的限制。

委托给：

• 无

适用场景

• 首次设置测试覆盖率强制检查
• 验证现有 Husky／测试设置是否配置正确
• 配置用于测试覆盖率的提交前钩子
• 调整覆盖率设置以适配不同的测试运行器

项目上下文发现

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/ 目录是否存在
   • 检查现有的提交前钩子
   • 检查 package.json 的依赖项中是否包含 Husky

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：在提交前钩子中使用 vitest run --coverage
• Mocha：将 nyc 或 c8 与 mocha 测试命令配合使用

覆盖率配置

Vitest：

• 不存在配置文件时，创建包含 test.coverage.thresholds 的 vitest.config.ts/js；如果配置文件已存在，则输出相应代码片段
• 配置 v8 覆盖率提供程序，并在缺少 @vitest/coverage-v8 时安装
• 默认阈值：行覆盖率 80%、分支覆盖率 75%、函数覆盖率 80%、语句覆盖率 80%

Mocha + nyc：

• 创建或更新 .nycrc.json，设置覆盖率阈值
• 配置 text、html 和 lcov 报告器

提交前钩子

创建的钩子会：

• 在每次提交前运行带覆盖率检查的测试
• 覆盖率低于阈值时阻止提交（可配置）
• 找不到测试文件时可选择跳过

配置选项

命令行参数

• --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 更新或创建 Vitest 配置（provider 为 v8，软件包为 @vitest/coverage-v8）
• 提交前钩子：bunx vitest run --coverage

如需完整配置示例，请参阅 references/full-guide.md（§ Example vitest.config.ts）。

Mocha 项目

检测：

• 检查依赖项中是否包含 mocha
• 检查是否有覆盖率工具（nyc 或 c8）

配置：

• 为 nyc 创建或更新 .nycrc.json
• 提交前钩子：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. 生成提交前钩子脚本；设置强制执行行为（阻止或警告）。
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

故障排除

提交前钩子未运行

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

未检查覆盖率

• 确认测试命令包含覆盖率标志
• 检查覆盖率配置文件是否存在且正确
• 确保已安装覆盖率工具（Vitest 使用 @vitest/coverage-v8，Mocha 使用 nyc/c8）

即使测试通过，钩子仍然失败

• 检查覆盖率阈值是否可达到
• 查看覆盖率报告，确认哪些项目未达到阈值
• 考虑调整阈值或提高测试覆盖率

测试已运行，但未强制检查覆盖率

• 确认覆盖率配置文件中的阈值正确
• 检查测试运行器是否支持覆盖率（Vitest 需要 @vitest/coverage-v8，Mocha 需要 nyc/c8）
• 检查提交前钩子脚本中的命令是否正确

检测到多个测试运行器

此技能会按优先级顺序使用第一个检测到的运行器：Vitest > Mocha

资源

• Husky 文档：https://typicode.github.io/husky/
• Vitest 覆盖率：https://vitest.dev/guide/coverage
• nyc（Istanbul）：https://github.com/istanbuljs/nyc