sonar-coverage

SonarQube — 覆盖率

找出测试覆盖率不足的文件，并精确定位需要添加测试的代码行。

用法

sonar-coverage                              # worst-covered files in the current project
sonar-coverage my-project                   # worst-covered files in a specific project
sonar-coverage my-project --max 50          # only files with coverage <= 50%
sonar-coverage my-project --file src/auth/login.py  # line-by-line detail for one file

前提条件

此技能要求配置 SonarQube MCP 服务，并且会话中可使用工具 mcp__sonarqube__search_files_by_coverage 和 mcp__sonarqube__get_file_coverage_details。

继续之前，请确认这些工具可以使用。如果不可用，请先尝试第 3 步中的 sonar api CLI 备用方案，再决定是否放弃——不要编造其他 CLI 命令（例如，sonar mcp call 或 sonar coverage 并不存在）。

如果 CLI 备用方案也失败（例如，未安装或未通过身份验证的 sonar，或者无法解析项目密钥），请进一步排查原因——检查此 Agent 的配置中是否启用了 sonarqube MCP 服务。

• 未启用 / 未注册 → 建议运行 sonar-integrate 技能。
• 已启用但工具仍不可用 → 配置正确，但服务启动失败。最常见的原因是容器运行时未运行——MCP 服务通过 sonar run mcp 在 Docker/Podman/Nerdctl 中启动，因此即使配置正确，守护进程停止时也不会提供任何工具。请自行运行 docker ps（如果不可用，则尝试 podman ps / nerdctl ps）以确认具体原因：如果命令报错，说明运行时未启动；用户启动运行时后，请确认同一命令可以成功执行，再让他们重启 Agent 会话。

无论哪种情况，都请向用户显示：

无法连接 SonarQube MCP 服务，或未找到项目密钥。

可能的原因：

• MCP 服务未注册 — 调用 sonar-integrate 技能以配置 SonarQube MCP 服务，然后重启 Agent 会话
• 容器运行时未运行 — SonarQube MCP 服务在容器（Docker、Podman 或 Nerdctl）中运行；请启动容器运行时，然后重启 Agent 会话
• 未配置凭据 — 调用 sonar-integrate 技能
• 项目密钥错误，或 MCP 配置中没有默认项目 — 传入显式密钥，或检查 sonar-project.properties / 为此项目重新运行 sonar-integrate 技能

然后询问用户是否现在运行 sonar-integrate 技能（是/否）。简要说明其作用：检查用户计算机上的 SonarQube 设置——安装或更新 sonarqube-cli 并验证身份验证——并为此 Agent 重新配置集成，包括 SonarQube MCP 服务和机密扫描钩子。如果用户确认，请自行调用 sonar-integrate 技能，并在本次会话中从头到尾执行；然后请用户确保容器运行时（Docker、Podman 或 Nerdctl）正在运行，并重启 Agent 会话，以便使用新的 MCP 工具；如果用户拒绝，则停止。

说明

步骤 1：解析项目密钥（仅在需要时）

sonar-integrate 技能为此工作区保存了默认项目后，MCP 工具有时不需要 projectKey。仅当必须传入密钥时（工具架构要求，或用户指定了其他项目）才解析密钥：

• 如果用户提供了项目密钥，则使用该密钥。
• 否则，在仓库根目录的 sonar-project.properties 中查找 sonar.projectKey。
• 如果仍未找到，MCP 调用中省略 projectKey，并使用集成默认值。

步骤 2：解析用户提供参数中的可选标志

标志	含义
--max <n>	仅返回覆盖率 ≤ n% 的文件（对应 maxCoverage）
--pr <id>	分析拉取请求，而不是主分支
--file <key>	跳过文件列表，直接查看此文件密钥的逐行详情

步骤 3：运行相应流程

流程 A — 文件列表（默认，不使用 --file）

调用 mcp__sonarqube__search_files_by_coverage。仅当你在第 1 步中解析出了 projectKey 且工具要求时，才包含 projectKey；否则省略。

{
  "projectKey": "<only-if-required>",
  "maxCoverage": <n>,       // if --max was given
  "pullRequest": "<id>",    // if --pr was given
  "pageSize": 20
}

当集成默认项目生效时，完全从负载中省略 projectKey。省略未使用的可选字段。

将结果按覆盖率升序整理成表格：

## Coverage — `my-project`

Files with lowest coverage (worst first):

| File                | Coverage |
| ------------------- | -------- |
| src/auth/login.py   | 12.5%    |
| src/utils/crypto.py | 23.0%    |
| src/api/routes.py   | 41.8%    |

如果未返回文件（所有文件都超过阈值），请说明：“所有文件均达到覆盖率阈值。”

然后提供进一步检查选项： “你可以让我检查这些文件中任意一个文件的未覆盖行，也可以调用 sonar-coverage 技能并使用 --file <file-key>（仅在需要时添加项目密钥）。”

如果 mcp__sonarqube__search_files_by_coverage 不可用，请回退到 sonar api。 这需要显式项目密钥（没有 MCP 默认值）——如果第 1 步未解析出项目密钥，请询问用户或调用 sonar-list-projects，然后停止。

sonar api get "/api/measures/component_tree?component=<project-key>&metricKeys=coverage,line_coverage,branch_coverage&qualifiers=FIL&strategy=leaves&s=metric&metricSort=coverage&asc=true[&pullRequest=<id>]"

使用 metricKeys。如果调用意外返回 400，添加 -v 以查看实际服务器错误。从每个组件的 measures 数组中读取 coverage，并按上述相同的表格格式呈现。

流程 B — 行详情（提供了 --file <key>，或用户要求检查某个文件时）

调用 mcp__sonarqube__get_file_coverage_details：

{
  "key": "<file-key>",
  "pullRequest": "<id>"   // if --pr was given
}

文件密钥格式为 <projectKey>:<path>，例如 my-project:src/auth/login.py。 如果用户只提供路径，则在已解析出项目密钥时将其加在路径前面；如果集成提供默认项目，详情工具可能接受路径，也可能接受 MCP 架构文档中的密钥格式——请遵循工具架构。

呈现未覆盖和部分覆盖的行：

## Coverage Detail — `src/auth/login.py`

Overall coverage: **12.5%**

### Uncovered lines
Lines with no test coverage: 14, 15, 23, 45–52, 67

### Partially covered branches
| Line | Covered branches | Total branches |
| ---- | ---------------- | -------------- |
| 30   | 1                | 2              |
| 61   | 0                | 2              |

如果文件已完全覆盖，请说明：“此文件中的所有行均已覆盖。”

如果 mcp__sonarqube__get_file_coverage_details 不可用，请回退到 sonar api：

sonar api get "/api/sources/lines?key=<file-key>[&pullRequest=<id>]"

每个返回的行都包含覆盖率字段（已覆盖/未覆盖、分支命中次数）——据此整理未覆盖行列表和部分覆盖分支表格。

如果这也失败，请显示标准消息——不要进一步猜测命令。

第 4 步：后续步骤

• 要为未覆盖行编写测试：“请让我为上述未覆盖行添加测试。”
• 要检查同一文件中的质量问题：“调用 sonar-list-issues 技能并使用 --component <file>。”
• 要检查质量门禁：“调用 sonar-quality-gate 技能（仅当你未使用集成默认项目时才添加项目密钥）。”