coverage-analysis

覆盖率分析

目的

说明 .NET 覆盖率证据能够证明什么，核对目标计算，并找出阻碍进展的代码。仅当用户明确要求分析风险热点、CRAP、按风险排序优先级或重构安全性时，才添加复杂度/CRAP 排名。

何时使用

用于解读提供的 .NET 行/分支/条件覆盖率证据、覆盖率缺口和停滞情况、目标计算，或明确要求基于覆盖率分析整个项目的风险。

何时不使用

• 对指定方法、类或文件进行 CRAP/重构安全性分析——改用 crap-score 技能
• 静态分析源代码与测试的对应关系，或列出没有测试的文件——改用 find-untested-sources
• 分析现有测试中的行为缺口或伪变异缺口——改用 test-gap-analysis
• 分析测试特征/类别分布，或按测试类型分析覆盖率构成——改用 test-tagging
• 编写或生成测试——本技能用于指出需要测试的地方，不负责编写测试
• 与覆盖率或 CRAP 分析无关的一般测试执行
• 仅收集 .NET 覆盖率，或只打印原始百分比而不进行诊断——改用 run-tests；收集或分析非 .NET 覆盖率时使用原生工具。解读 .NET 行/分支覆盖率缺口仍属于本技能范围

输入

输入	必填	默认值	说明
项目/解决方案路径	否	当前目录	.NET 解决方案或项目的路径
行覆盖率阈值	否	80%	可接受的最低行覆盖率
分支覆盖率阈值	否	70%	可接受的最低分支覆盖率
现有 Cobertura 路径	否	仅在未提供时发现	首选输入；报告可用时绝不重新运行测试
CRAP 阈值	否	30	仅用于明确要求的风险/CRAP 分析
热点数量	否	3	仅用于明确要求的风险分析；最多为 10，除非用户要求更多

从工作区中发现可选输入。当前目录或已提供的报告足以开展分析时，不要询问项目路径。

选择最小匹配路径

用户意图	必须执行	不要执行
解释提供的摘录、条件或摘要	直接依据提供的证据作答	使用工具、分析 CRAP、进行发现、创建报告文件
解读提供的 Cobertura 路径或诊断覆盖率停滞	阅读该报告，核对总数，指出所有重要缺口，并直接作答	重新运行测试、安装工具、计算 CRAP，或生成文件，除非用户明确要求
排列风险热点、计算整个项目的 CRAP，或评估重构安全性	使用提供的/现有报告，阅读 references/guidelines.md，并在排名前计算 CRAP	仅按覆盖率排名，或使用完整报告模板，除非用户要求
在没有报告时分析覆盖率	调用 run-tests，使用与代码库兼容的运行器收集覆盖率，然后分析生成的报告	自行选择或执行测试命令；除非用户要求分析风险，否则不计算 CRAP
生成完整的 Markdown/HTML/CSV 报告	先给出直接答复；然后阅读 references/output-format.md 或 references/report-generation.md	在答复前生成报告

诸如分析覆盖率、是什么阻碍了覆盖率或为什么覆盖率停滞不前等说法，本身并不表示用户要求分析 CRAP。明确的信号包括风险热点、CRAP、按复杂度加权的优先级、是否适合重构，或提出同等要求，即将复杂度与覆盖率结合起来分析。

现有数据快速路径

当用户提供覆盖率摘录、摘要或有效的 Cobertura 路径时：

• 将其视为权威输入，并从此处开始。
• 除非需要进行源代码映射，否则不要查找解决方案或测试项目。
• 不要运行 dotnet test、安装 ReportGenerator、添加覆盖率包，也不要读取 references/setup-discovery.md 或 references/report-generation.md。
• 除非用户要求保存报告或完整报告，否则不要编写 coverage-analysis.md，也不要创建报告目录。
• 对于解读和平台期问题，只解析回答所需的证据。对于明确要求的项目范围风险分析，按 references/guidelines.md 中的说明使用捆绑脚本。

读取或查看操作失败，并不能证明指定路径不存在。先对失败进行分类，然后针对该路径进行一次定向存在性探测；仅当确认问题属于工具可用性、传输或路径规范化失败时，才使用规范化路径或备用读取器，并且仅在验证规范路径仍位于工作区内之后进行。遇到内容排除、权限／策略、工作区边界或未知故障时应停止。只有独立探测也失败时，才能报告路径不存在；不要扩大搜索范围，也不要用其他制品替代。

收集路径

仅当不存在可用的覆盖率证据，且用户要求的分析需要此证据时，才使用此路径。

1. 阅读 references/setup-discovery.md。
2. 优先使用在用户指定根目录下发现的现有 Cobertura。
3. 如果没有，则调用 run-tests 来选择仓库覆盖层、平台、运行器和命令，并让其为每个入口点收集一次 Cobertura。
4. 分析生成的 Cobertura。仅当用户明确要求风险分析时，才计算 CRAP。

当工作区包含此路径所需的项目／测试清单文件时，直接执行发现，并委托 run-tests 进行收集。不要要求用户附加文件或预先运行覆盖率收集，因为当前工作区允许你检查并生成这些内容。

不要修改生产代码。收集所需的任何附带测试项目更改均由 run-tests 负责；在最终分析中列出该更改及其还原命令。

自动收集路径适用于 SDK 风格项目。对于经典非 SDK 项目或 packages.config 项目，只能使用仓库自带的覆盖率命令。如果没有此类命令，则停止并请求 Cobertura XML。绝不要迁移项目、注入 SDK 风格的提供程序、创建包装项目，或报告来自其他程序集的替代覆盖率。

解读与算术不变量

• 命中一行只能证明代码执行过，不能证明两个决策结果都已覆盖。
• condition-coverage="50% (1/2)" 只能证明报告中的一个结果已执行，但无法说明是哪一个。建议强制触发相反的结果。没有源代码时，绝不要臆测可能的谓词，也不要声称缺少 true 还是 false。请说明复合谓词需要分别测试各个操作数，并在适用时覆盖短路组合；没有源代码或更完整的 XML 时，不要推断具体组合。
• 根据 Cobertura 的已覆盖行数和有效行数推算总体数据。对于目标 T，所需的已覆盖行数为 ceiling(valid lines × T)。
• 预计覆盖率为 (current covered lines + newly covered distinct lines) / valid lines。请说明诸如某个方法将被完全覆盖等假设。
• 当用户询问某个成员能否达到目标时，请给出其预计的最高覆盖率，并至少提供一种由所给成员或行数增量构成的具体可行组合。如果所给组合都不足以达到目标，请明确说明。
• 对于涉及多个成员的目标，请列出准确的组合以及由此得到的已覆盖行数 / 有效行数；只说“与另一个成员组合”并不完整。
• 对照项目总体数据核对各成员的覆盖缺口。方法行范围可能重叠，或遗漏类级行，因此不要将方法行数相加后当作项目总体数据。
• 除非某个成员未覆盖的不同代码行数与项目总体数据完全吻合，且没有其他低于阈值的成员，否则绝不要称该成员是唯一、全部或所有剩余缺口。
• 列出所有提供的或提取出的低于阈值的成员，但详略应适度：先说明阻碍项，其余内容用一句话或简洁表格概述。

回复要求

在前 2–4 句话中回答用户的问题。

• **摘录或算术问题：**给出一项解释，并说明下一项测试或成员优先级。不使用仪表板。
• **现有报告解读或覆盖率停滞：**说明总体行覆盖率 / 分支覆盖率、阻碍成员、经核对的目标影响，以及 1–3 条建议。最多使用一个简洁表格。
• **明确要求风险 / CRAP 分析：**默认列出实际风险最高的 3 个热点，并提供复杂度 / 覆盖率 / CRAP 数值、剩余标记数量和 1–3 个优先事项。不要将已完全覆盖的低风险方法列入热点表。除非用户要求更多，否则最多列出 10 行。对于重构安全性，按 CRAP 而非原始覆盖率为高风险方法排序，然后单独列出覆盖良好且相对安全的方法。
• **明确要求完整报告：**读取 references/output-format.md。仅在此时保存报告。

只报告实际存在的产物。未要求生成文件时，不要声称输出路径无法访问，也不要提及可选文件写入失败。

可选报告

HTML / CSV / Markdown 文件不属于常规分析内容。仅当用户明确要求报告文件或 CI 产物时才生成。

1. 首先直接回答覆盖率 / 风险问题。
2. 如需完整 Markdown 报告，读取 references/output-format.md 并保存报告。
3. 如需 HTML / CSV，再读取 references/report-generation.md。直接回答之前不要安装 ReportGenerator，安装失败后也不要重试。

验证

• 确认使用了用户提供的报告，且未运行测试或安装工具。
• 在推算影响之前，核对已覆盖、有效和未覆盖行数。
• 确认每个所述阻碍项都有用户提供或提取出的证据支持。
• 如用户要求 CRAP 分析，请使用 references/guidelines.md 抽查一个分数。
• 如用户要求生成文件，请先确认文件存在，再报告其路径。

常见陷阱

• 已有报告却触发设置工作 — 停止。先分析指定的制品。
• 通用分析触发 CRAP — 停止。只有明确提出风险意图时才需要 CRAP。
• 将一个方法称为全部差距 — 先核对不同的未覆盖行以及完整的低于阈值集合。
• 小请求却生成仪表板 — 缩小范围，直接回答或提供一张表格即可。
• 收集时未生成 Cobertura — 报告收集失败；不要编造替代覆盖率。
• 编译器生成的方法名 — 在将可疑的异步、lambda 或局部函数名称作为用户编写的成员展示前，先对照源代码进行核实。
• 测试退出代码为 1 — 覆盖率可能仍然存在；附上警告后继续。其他非零构建失败会中止收集流程。