codacy-code-review

Codacy 代码评审

**术语表：**有关 Codacy 概念（问题、发现项、严重性、覆盖率、工具、规则等）的通用定义，请参阅 glossary.md。

此技能通过 Codacy 数据丰富代码评审。它可与任何现有代码评审流程（代码评审技能、CodeRabbit、手动评审等）配合使用，在此基础上补充 Codacy 专属数据。

先决条件

• Codacy Analysis CLI（codacy-analysis）——用于快速本地分析。请参阅 codacy-analysis-cli 了解设置方法。
• Codacy Cloud CLI（codacy）——用于获取覆盖率数据、质量门状态和忽略问题。请参阅 codacy-cloud-cli 了解设置方法。

两个 CLI 共用 ~/.codacy/credentials 中的凭据，因此登录一次即可用于两者。

本地分析与云端分析

此技能使用两种互补的分析来源：

来源	提供内容	速度
Analysis CLI（本地）	PR 更改中的问题和安全发现项	即时——无需推送或远程分析
Cloud CLI（远程）	覆盖率变化、质量门、重复代码、问题管理（忽略/取消忽略）	需要推送 PR，并由 Codacy 进行分析

问题检测优先使用本地分析——它会立即对当前工作树运行 --pr，无需等待远程分析。使用 Cloud CLI 补充覆盖率数据和质量门状态，并管理问题（忽略/取消忽略）。

Analysis CLI 可能不支持 Codacy Cloud 运行的所有工具。如果项目使用本地不可用的工具（使用 codacy-analysis analyze --inspect --output-format json 检查），请指出部分发现项可能只会出现在云端结果中。

Codacy PR 数据的工作方式

• 云端数据反映 PR 的 HEAD 提交——显示的远程分析始终针对最新推送到 PR 分支的内容，而非特定提交。
• 本地分析反映工作树——codacy-analysis analyze --pr 会将当前分支与 PR 的目标分支进行比较，即使尚未推送也能发现问题。
• 忽略问题仅可在云端操作——更改会立即在 Codacy 上生效，但其他配置更改（规则、工具）要等到下一次远程分析后才会生效。
• 远程分析过时或缺失——如果 Cloud PR 分析似乎已过时或不完整，请使用 codacy pull-request <provider> <org> <repo> <prNumber> --reanalyze-and-wait 触发重新分析，并等待其完成（每 10 秒轮询一次，最长 20 分钟）。如果不想等待，请改用 --reanalyze，然后手动重新检查。
• 自动检测——在仓库内运行时，Cloud CLI 会从 git 远程地址自动检测 provider/org/repo。像 codacy pull-request <prNumber> 这样的命令无需显式指定参数即可运行。

评审工作流

评审拉取请求时，请按以下步骤操作。必须完成所有步骤，不要跳过。

Code Review Progress:
- [ ] Step 1: Gather PR context (title, description, linked ticket)
- [ ] Step 2: Run local analysis on PR changes
- [ ] Step 3: Fetch Cloud PR data (coverage, quality gate)
- [ ] Step 4: Check introduced issues
- [ ] Step 5: Check coverage
- [ ] Step 6: Verify alignment with ticket and PR description
- [ ] Step 7: Propose test plan and check coverage gaps
- [ ] Step 8: Summarize and suggest improvements

步骤 1：收集 PR 上下文

从源代码托管平台（GitHub、GitLab、Bitbucket）获取拉取请求元数据：

• PR 标题和描述
• 关联的工单或问题（Jira、GitHub Issues、Linear、本地规格说明等）——查看描述、分支名称和提交消息

如果关联了工单，也请获取其内容。

步骤 2：对 PR 更改运行本地分析

运行 Analysis CLI，立即获取已更改文件的分析结果，无需等待远程分析：

# If the PR already exists (compares against the PR's target branch)
codacy-analysis analyze --pr --fail-if-missing --output-format json

# If the PR hasn't been created yet (compares against the merge base of the current branch)
codacy-analysis analyze --diff --fail-if-missing --output-format json

如果拉取请求已创建，请使用 --pr；如果在创建 PR 前审查分支上的更改，请使用 --diff。这两个选项都会对已更改的文件运行所有本地可用的工具。

**--fail-if-missing 在这里很重要：**如果不使用它，不可用的扫描器会被静默跳过，运行仍会以 0 退出且没有问题——即使什么都没有扫描，审查者也会看到“未引入问题”。

如果运行被阻止（errors[].kind == "UnavailableTools"），或项目尚未初始化，请先安装，然后重新运行严格模式命令（这两个标志不能同时使用）：

codacy-analysis init   # only if not initialized
codacy-analysis analyze --pr --install-dependencies --output-format json
codacy-analysis analyze --pr --fail-if-missing --output-format json

解析本地结果以查找问题——这些结果可立即获取，涵盖了大部分审查内容。在断定 PR 未引入问题之前，请确认 toolResults 非空（为空表示没有扫描任何内容），并将任何 capability.unavailable 或仅限云端的工具列入分析覆盖情况。

步骤 3：获取 Cloud PR 数据（覆盖率、质量门禁）

覆盖率、质量门禁状态和重复度指标仅可通过 Codacy Cloud 获取：

codacy pull-request <provider> <org> <repo> <prNumber>

返回的数据包括：是否符合标准、覆盖率变化、复杂度变化、重复度变化以及已更改的文件。

如需查看带有行内覆盖率注释的差异：

codacy pull-request <provider> <org> <repo> <prNumber> --diff

如果远程分析已过期或缺失，请触发重新分析并等待完成：

codacy pull-request <provider> <org> <repo> <prNumber> --reanalyze-and-wait

此操作会阻塞，直到重新分析完成（最长 20 分钟），并报告变化。等待期间，请继续使用步骤 2 的本地结果进行审查。如需触发后立即返回的重新分析，请改用 --reanalyze。

步骤 4：检查新引入的问题

合并本地分析（步骤 2）和 Cloud 数据（步骤 3）中的发现：

• 本地问题通常最先可用——请立即据此开始审查
• Cloud 问题可能包括本地不可用的工具发现的问题——远程分析完成后再进行交叉核对
• 记录每个问题的严重程度、类别和文件位置
• 将严重和高严重程度的问题标记为阻塞项

如果问题看起来是误报，请建议通过 Cloud CLI 忽略它们：

# Ignore a specific issue in this PR
codacy pull-request <provider> <org> <repo> <prNumber> --ignore-issue <issueId> --ignore-reason FalsePositive

# Ignore all issues Codacy identified as potential false positives in one go
codacy pull-request <provider> <org> <repo> <prNumber> --ignore-all-false-positives

# Unignore if needed
codacy pull-request <provider> <org> <repo> <prNumber> --unignore-issue <issueId>

如果相同的误报模式在多个 PR 中反复出现，请改用 configure-codacy 建议停用该模式。

步骤 5：检查覆盖率

覆盖率数据来自 Cloud CLI（步骤 3）。请检查：

• 总体覆盖率变化（上升还是下降？）
• PR 引入了未覆盖代码行的文件
• 使用 --diff 输出查看哪些具体行缺少覆盖率（✘ 标记）

将新增未覆盖代码行的文件标记为需要测试。

步骤 6：核对一致性

**与工单/问题的一致性：**检查代码更改是否满足所述要求。记录工单中描述但未体现在更改中的功能，以及超出工单范围的更改。

**与 PR 描述的一致性：**确认描述准确反映了更改内容。记录不一致之处。

如果工单或 PR 描述缺失、不完整或不准确，请指出具体的改进建议。

步骤 7：提出测试计划

根据已更改的代码和覆盖率数据：

1. 列出应测试的场景（正常路径、边缘情况、错误情况）
2. 针对每个场景，检查 PR 差异中是否已有相应测试
3. 标记没有对应测试且在 Codacy 中没有覆盖率的场景

步骤 8：总结

以结构化形式呈现审查摘要：

## Codacy Review Summary

### Quality gate
[Pass / Fail — from Codacy PR analysis]

### Issues introduced
[List issues by severity, or "None — see Analysis coverage"]

### Analysis coverage
[Tools that ran; any skipped (with reason) or cloud-only]

### Coverage
[Delta, uncovered lines in new code]

### Alignment
- Ticket: [aligned / gaps noted]
- PR description: [accurate / suggestions]

### Test plan
[Proposed scenarios and whether tests exist]

### Suggested improvements
- PR description: [if applicable]
- Ticket/issue: [if applicable]

其他代码审查技能处于启用状态时

如果其他代码审查技能（例如 code-review skill、CodeRabbit）已完成审查，请在该审查中添加 Codacy 数据部分，不要替换原审查。遵循上述步骤 2–7，并在后面附上 Codacy 的发现。