skill-coverage-audit

宿主：Codex CLI — 此技能原为 Claude Code 设计，后适配至 Codex。 交叉引用命令在 Codex 中使用已安装的技能名称，而非 /octo:* 斜杠命令。 请使用当前 Codex 会话中的 Shell 和子 Agent 工具。除非当前会话已提供相应能力，否则不要声称可使用某个提供商、模型或宿主子 Agent。 有关宿主工具的对应项，请参阅 skills/blocks/codex-host-adapter.md。

测试覆盖率审计

实施前的制品一致性检查

在规范／计划／任务边界处调用时，请使用功能边界适配器，而非此技能的代码测试生成模式。它会自动运行范围受限的确定性检查，检查覆盖率、声明的路径、稳定 ID、明确的术语／枚举／数量以及已验证的策略引用。单个制品会跳过分析；检查通过则不占用席位。报告仅供参考，并会引用原始来源。升级处理最多使用一个独立席位；若语义审查不可用或失败，确定性结果仍可使用。

概述

追踪差异中的每条代码路径，将每条路径与现有测试对应起来，可视化覆盖率缺口，并为未覆盖的路径自动生成测试。

核心原则： 追踪已更改文件中的代码路径 -> 与现有测试对应 -> 评估覆盖质量 -> 为缺口生成测试 -> 报告前后数量。

上限与限制

这些硬性限制可防止分析失控：

• 每次审计最多 30 条代码路径。 如果差异产生的路径超过 30 条，请按复杂度和风险排序（优先处理错误路径、安全敏感分支和公共 API 接口）。
• 每次审计最多生成 20 个测试。 优先填补影响最大的缺口。
• 每项测试的探索时间上限为 2 分钟。 如果理解单个测试路径耗时超过 2 分钟，请将其标记为“需要人工审查”，然后继续。

阶段 1：追踪代码路径

步骤 1：识别已更改的文件

确定差异范围。使用最相关的来源：

# PR diff
git diff --name-only main...HEAD

# Staged changes
git diff --name-only --cached

# Last commit
git diff --name-only HEAD~1..HEAD

仅筛选源代码文件（排除配置文件、文档和生成文件）。

步骤 2：追踪每个分支中的数据流

对于每个已更改的文件，必须追踪：

1. 条件语句 -- 每个 if/else、switch/case、三元表达式和模式匹配。每个分支都是一条独立的代码路径。
2. 错误路径 -- 每个 catch、throw、错误返回、验证失败，以及带错误的提前返回。原因：错误路径是最常见的未测试 Bug 来源。
3. 函数调用 -- 从已更改代码调用的每个函数。深入追踪被调用函数一层，以识别集成边界。
4. 循环边界 -- 循环中的空集合、单项和多项路径。
5. 守卫子句 -- 每个提前返回、空值检查和权限门控。

步骤 3：构建代码路径清单

生成结构化清单：

## Codepath Inventory: [filename]

| # | Path Description | Type | Risk |
|---|-----------------|------|------|
| 1 | validateUser() happy path | conditional | low |
| 2 | validateUser() missing email | error | medium |
| 3 | validateUser() invalid format | error | medium |
| 4 | processOrder() empty cart guard | guard | high |
| 5 | processOrder() payment timeout | error | high |
| 6 | processOrder() success | conditional | low |

类型类别： conditional、error、guard、loop-boundary、integration、async

风险评估： high = 面向用户的故障或数据丢失，medium = 行为降级，low = 外观或日志问题

阶段 2：测试映射与质量评分

步骤 1：搜索现有测试

对于差异中的每个文件，在测试目录中搜索相关测试：

# Find test files that reference the changed file or its exports
# Search by filename pattern
find tests/ -name "*[changed_file_stem]*" -type f

# Search by import/require of the changed module
grep -rl "import.*from.*[module_name]" tests/
grep -rl "require.*[module_name]" tests/

# Search by function name references
grep -rl "[function_name]" tests/

步骤 2：评估测试质量

根据以下标准评估每条代码路径的现有测试覆盖率：

评级	含义	标准
★★★	已测试行为与边界情况	测试验证行为，并覆盖边界条件、错误情况和边界输入
★★	已测试正常路径	测试覆盖成功路径，但遗漏错误分支或边界情况
★	仅冒烟测试	存在测试，但只检查函数能否运行而不报错（没有有意义的断言）
☆	未找到测试	没有测试涉及此代码路径

步骤 3：生成覆盖率映射

将每条代码路径映射到其测试覆盖情况：

## Coverage Map: [filename]

| # | Codepath | Test File | Rating | Notes |
|---|----------|-----------|--------|-------|
| 1 | validateUser() happy path | test-user.sh:42 | ★★★ | Asserts valid + invalid inputs |
| 2 | validateUser() missing email | test-user.sh:58 | ★★ | Tests missing, not malformed |
| 3 | validateUser() invalid format | -- | ☆ | No test for format validation |
| 4 | processOrder() empty cart guard | -- | ☆ | Guard clause untested |
| 5 | processOrder() payment timeout | test-orders.sh:30 | ★ | Checks no crash, no assertions |
| 6 | processOrder() success | test-orders.sh:15 | ★★★ | Full integration test |

阶段 3：覆盖率图表

完成映射后，生成 ASCII 覆盖率摘要。这是主要输出成果。

COVERAGE: 5/12 paths tested (42%)
  Code paths: 3/5 (60%)
  User flows: 2/7 (29%)
GAPS: 7 paths need tests

按类别细分：

BY TYPE:
  conditional:  3/4 tested (75%)  ████████░░
  error:        1/5 tested (20%)  ██░░░░░░░░
  guard:        0/2 tested  (0%)  ░░░░░░░░░░
  integration:  1/1 tested (100%) ██████████

BY RISK:
  high:    1/3 tested (33%)  ███░░░░░░░
  medium:  2/5 tested (40%)  ████░░░░░░
  low:     2/4 tested (50%)  █████░░░░░

已覆盖部分使用实心方块，未覆盖部分使用浅色阴影。使用 10 个字符的条形图。始终显示精确分数和百分比。

阶段 4：自动生成测试

步骤 1：检测项目测试惯例

生成任何测试之前，你必须检测项目的测试模式：

**Detected Test Conventions:**
- Framework: [jest/vitest/pytest/bash/go test/etc.]
- Location: [tests/ | __tests__/ | src/**/*.test.* | etc.]
- Naming: [test-*.sh | *.test.ts | *_test.go | etc.]
- Style: [BDD describe/it | xUnit | TAP | custom]
- Helpers: [test-utils.ts | conftest.py | helpers/ | etc.]
- Assertion library: [built-in | chai | assert | etc.]

步骤 2：为未覆盖路径生成测试

对于每个没有测试和仅有冒烟测试的代码路径，生成一个测试，要求：

1. 遵循项目命名惯例 -- 使用相同的目录结构和文件命名模式
2. 使用现有测试辅助工具 -- 从项目已使用的相同测试工具中导入
3. 测试行为，而非实现 -- 断言可观察到的结果，而非内部状态
4. 覆盖特定缺口 -- 针对阶段 1 中发现的确切分支或错误路径
5. 包含边界情况 -- 力求每个生成的测试都达到完整覆盖

步骤 3：展示生成的测试

对于每个生成的测试，展示：

### Generated: test for [codepath description]
**Covers:** Codepath #N from [filename]
**Raises coverage:** from no-test to full coverage

[test code block]

步骤 4：报告前后变化

生成所有测试后，展示覆盖率变化：

BEFORE: 5/12 paths tested (42%)
AFTER:  11/12 paths tested (92%)
  New tests generated: 6
  Remaining gaps: 1 (manual review needed)

与其他技能集成

与 flow-deliver / skill-code-review 集成

覆盖率审计是代码审查的补充。在交付阶段调用时：

1. 代码审查评估质量和正确性
2. 覆盖率审计评估测试完整性
3. 两者共同决定是否发布

与 skill-tdd 集成

如果覆盖率审计发现新代码存在缺口，建议用户在下一轮采用 TDD。覆盖率审计修复现有缺口；TDD 防止未来出现缺口。

与 skill-verification-gate 集成

生成测试后，使用 skill-verification-gate 运行测试套件并确认新测试通过。

危险信号——请勿这样做

操作	错误原因
统计代码行而非路径	行覆盖率完全无法体现分支覆盖率
未检查惯例就生成测试	不符合项目风格的测试会被拒绝
测试实现细节	脆弱的测试会在重构时失效
跳过错误路径	大多数 Bug 都藏在错误路径中
超过 30 条路径的上限	分析会失去焦点，且耗时过长
生成超过 20 个测试	收益递减；应聚焦于影响最大的部分
在一条路径上花费超过 2 分钟	标记为需要人工审查，然后继续

快速参考

1. TRACE   -> Identify all codepaths in the diff (max 30)
2. MAP     -> Find existing tests for each path
3. SCORE   -> Rate coverage quality (no-test / smoke / happy-path / full)
4. DIAGRAM -> ASCII coverage visualization
5. GENERATE -> Auto-create tests for gaps (max 20)
6. REPORT  -> Before/after test counts