eliteforge-sonar-pmd-generator

Sonar PMD 生成器（规范驱动、端到端）

概述

此技能可将编码规范文档转换为可强制执行的 PMD 规则，并通过真实的 SonarQube 服务工作流进行验证。 完成任务需要端到端的完整链路：解析规范、进行 L1/L2/L3/L4 分类、为 L1-L2 生成 PMD 规则集、规划 L3 自动化、规划 L4 审查、打包自定义 sonar-pmd 插件、启动 Docker Sonar、扫描测试项目，以及在服务端进行验证。

环境变量

• ELITEFORGE_SKILL_SONAR_PMD_HOST [可选]：用于参考命令片段的 SonarQube 基础 URL；脚本参数可以覆盖此值。
• ELITEFORGE_SKILL_SONAR_PMD_TOKEN [可选]：用于本地验证片段的 SonarQube API 令牌；切勿打印此值。
• ELITEFORGE_SKILL_SONAR_PMD_PROJECT_KEY [可选]：API 证据片段使用的 Sonar 项目密钥。
• ELITEFORGE_SKILL_SONAR_PMD_PLUGIN_KEY [可选]：API 证据片段使用的自定义 Sonar 插件密钥。
• ELITEFORGE_SKILL_SONAR_PMD_RULE_REPO_KEY [可选]：API 证据片段使用的自定义规则仓库密钥。
• ELITEFORGE_SKILL_SONAR_PMD_PROFILE_KEY [可选]：API 证据片段使用的质量配置密钥。

渐进式加载

• 首先阅读 references/workflow-playbook.md，了解完整的执行顺序。
• 实现或调试插件模块时，阅读 references/plugin-packaging-blueprint.md。
• 在 Docker 中启动 Sonar 并运行测试扫描时，阅读 references/docker-sonar-validation.md。
• 收集验证证据时，阅读 references/sonar-api-evidence-checklist.md。
• 扫描后使用 scripts/verify_sonar_plugin.sh 快速进行基于 API 的冒烟验证。

触发条件

请求包含以下一项或多项意图时，使用此技能：

• 将编码规范转换为 PMD 规则。
• 自动将规范条款分类为 L1/L2/L3/L4。
• 构建或扩展自定义 Sonar PMD 插件/配置。
• 使用 Docker 和真实扫描在 SonarQube 中验证 PMD 插件行为。
• 证明自定义规则在 Sonar 中可见且能够生成问题。

必需输入

• 一个或多个规范文件路径。
• 每份规范对应的目标语言。
• 插件工作区路径（或搭建工作区的许可）。
• 测试项目路径（或搭建项目的许可）。
• 可选的生成产物输出目录（默认值：pmd-governance/）。
• 可选的配置名称（默认值：custom-spec-profile）。

分类约定（必须遵守）

• L1：可由目标语言的 PMD 内置规则覆盖。
• L2：可通过目标语言的 PMD AST XPath 规则表达。
• L3：无法或不应通过 PMD 表达，但可由其他自动化工具可靠检测，例如格式化工具、钩子、CI 任务、Checkstyle、Semgrep、ArchUnit 或构建插件。
• L4：由于规则取决于业务语义、架构意图或不稳定的启发式方法，因此需要人工审查或 AI 审查。
• 切勿强行使用脆弱的 PMD XPath 实现 L3 或 L4。

对于每条规范声明，记录：

• SPEC-ID
• 原始声明
• 目标语言
• 级别（L1/L2/L3/L4）
• 检测目标
• 触发条件
• 例外条件
• 严重级别
• 主要工具
• 执行阶段
• 实施计划
• 审查者备注（L4 必填）

端到端工作流（必需）

1. 解析规范陈述并分配 ID（SPEC-<LANG>-001，……）。
2. 自动将每条陈述分类为 L1/L2/L3/L4。
3. 生成治理产物：
   • mapping/spec-to-governance.csv
   • rulesets/custom-<lang>-ruleset.xml
   • automation/l3-tooling-plan.md
   • manual-review/l4-review-checklist.md
   • README.md
4. 仅使用 L1-L2 构建自定义 PMD 规则模块：
   • 包含映射的 L1 引用以及自定义 XPath/Java 规则 L2
   • 规则键/消息必须包含可追溯至 SPEC-ID 的信息
5. 为 L3 制定自动化计划：
   • 选择能够执行规则的最小稳定工具
   • 尽可能优先使用格式化工具或构建插件，而不是自定义脚本
   • 指明它在提交前、CI、构建期间还是 MR 检查中运行
6. 为 L4 制定审查计划：
   • 定义人工审查清单条目
   • 定义可选的 AI 审查提示词或评估标准
7. 构建自定义 Sonar 插件模块：
   • 注册 PMD 规则仓库
   • 将自定义规则加载到 Sonar 中
   • 提供默认质量配置文件（custom-spec-profile 或用户提供的名称）
8. 打包插件 JAR 并部署到 Sonar 插件目录（extensions/plugins）。
9. 在 Docker 中启动已加载自定义插件的 SonarQube Community。
10. 等待 Sonar 服务就绪并初始化令牌/项目绑定。
11. 准备测试项目：

• 如果提供了真实项目，则使用该项目；否则搭建一个最小项目
• 包含违规和合规的代码示例

12. 使用 Maven Sonar 插件触发实际扫描（mvn sonar:sonar）。
13. 通过 Sonar API/UI 验证插件有效性：

• 配置文件存在且处于激活状态
• 已列出并启用自定义规则
• 生成的问题包含规则键 + 文件 + 行号映射

14. 报告扫描证据和未解决的差距。

语言支持门槛

1. 检查 PMD 和 Sonar 集成路径是否支持目标语言。
2. 如果 PMD 不支持：
   • 如果其他自动化工具可以执行候选规则，则将其分类为 L3
   • 将其余条目分类为 L4
   • 生成自动化和审查两类输出
   • 建议使用替代分析器，并可选择导入通用外部问题

Sonar 集成

服务端插件执行：

• 首选此方式，因为此技能要求验证自定义插件。
• 扫描命令示例：
  • mvn -DskipTests sonar:sonar -Dsonar.host.url=http://localhost:9000 -Dsonar.token=<token>

Docker 验证基线

容器启动后的最低检查项：

• Sonar 健康检查端点报告服务已就绪。
• 插件已加载（可在市场/插件列表或启动日志中看到）。
• 可以使用该插件提供的质量配置文件。

扫描后的最低检查项：

• 违规示例中至少出现一个自定义规则问题。
• 合规示例不会触发该自定义规则。
• 问题映射到具体文件和行号。

不可妥协的规则

• 不要手工编写 PMD 报告；生成的发现必须来自实际分析。
• L1-L2 必须纳入 PMD 规则和自定义 sonar-pmd 插件。
• L3 条目必须导出到自动化工具计划中，不得强行纳入 PMD。
• L4 条目必须导出到人工或 AI 审查工作流中。
• 未提供 Docker Sonar 和实际扫描证据的端到端验证是不完整的。
• 首次部署应保持非阻断，除非用户明确要求设置 CI 门禁。

交付产物

• 治理产物（mapping、ruleset、L3 工具计划、L4 审查清单）。
• 自定义插件源代码和打包后的 JAR。
• Docker 启动命令和运行时证据。
• 测试项目扫描命令和结果摘要。
• 验证报告，列出配置文件键、规则键、问题数量和抽样问题位置。

故障排查清单

• 插件未加载：验证 Sonar／插件 API 的兼容性，并检查重启日志。
• 缺少配置文件：验证仓库键和配置文件注册代码。
• 未发现问题：确认配置文件绑定正确，并确认测试代码确实违反了规则。
• 误报激增：缩小 XPath 范围并添加反例。
• 扫描身份验证错误：验证令牌和 sonar.host.url 是否一致。