java-coding-quality

Java 质量门禁

面向 Java 代码交付前验证的工具门禁助手。用 JVM 插件链（PMD 7 + 自带规则集、SpotBugs + FindSecBugs）实跑扫描并按严重级修复，直到 Blocker/Critical 清零才算交付。

三条铁律

1. 工具兜底，不再造规范：约束靠实跑的静态扫描（PMD 7 + SpotBugs），不重复堆砌编码规则；发现的告警若属编码手法问题，用本技能 references 速查表修复。
2. 零侵入优先：默认在项目根建 .qualitygate/ 包装工程扫描，项目自身 pom 零改动；通过一次后才询问一次是否持久化进项目 pom，拒绝则不再问。
3. 安全告警不自行豁免：误报抑制必须附注释理由并经用户确认；FindSecBugs 安全类告警 Agent 一律不得擅自 suppress。

工具链

第 0 步：环境探测（激活时先执行）

读 pom.xml / build.gradle 一次性探测（读不到则一次问全，勿分多轮）：

1. 构建工具：Maven（有 pom.xml）还是 Gradle；mvn -v / gradle -v 是否可用。
2. 目标 JDK：maven.compiler.release / `` / sourceCompatibility——决定 PMD 的 targetJdk 与编译参数（SpotBugs 需先编译）。
3. 项目是否已配质量插件：pom/gradle 中是否已有 maven-pmd-plugin / spotbugs-maven-plugin / checkstyle / sonar——
   • 已配 → 直接复用项目自己的配置与规则集，不引入技能默认规则集（尊重团队既有基线）；仅在项目无规则集时才用技能自带的。
   • 未配 → 走「接入方式」用技能自带规则集扫描。
4. 无 Maven/Gradle 或不可用 → 告知无法实跑门禁，降级为「按 references 做人工对照检查」，并如实说明未做运行时验证。

接入方式（零侵入优先）

默认（零侵入）：在项目根建 .qualitygate/ 目录，写入包装 pom + 从技能 assets/ 拷入 pmd7-ruleset.xml；PMD 包装 pom 的 sourceDirectory 指向 ../src/main/java；SpotBugs 包装 pom 用 `` 指向 ../target/classes（被检项目须先 mvn compile）；把 .qualitygate/ 追加进 .gitignore。项目自身 pom 全程零改动。完整模板见 references/01-setup.md。

持久化（询问后）：.qualitygate/ 扫描通过一次后，询问一次是否把 PMD/SpotBugs 插件片段写入项目 pom（供团队 / CI 共享）；拒绝则保持零侵入、不再问。

门禁流程与退出条件

编译（SpotBugs 前置）→ PMD 扫描 + SpotBugs(FindSecBugs) 扫描 → 解析报告按严重级归并
→ 修复（Blocker→Critical→Major）→ 复扫 → Blocker/Critical 清零 → 交付

• 修复顺序：Blocker → Critical → Major；Minor 仅报告不强改。
• 退出条件：Blocker 与 Critical 必须清零才算通过；Major 尽量修，无法修的登记说明。
• 死循环保护：同一告警连续 2 轮修复仍无法消除 → 停下向用户说明原因并申请豁免，不无限重试。
• 严重级如何从 PMD priority / SpotBugs rank 映射到 Blocker/Critical/Major/Minor，见 references/04-fix-workflow.md。

误报 / 豁免规则

• 抑制手段（@SuppressWarnings("PMD.RuleName") / SpotBugs @SuppressFBWarnings / exclude filter）必须附注释写明理由且须用户确认后才可加。
• Agent 不得自行豁免安全类告警（FindSecBugs SECURITY 类别、PMD security 规则）；只能如实上报并给修复建议。
• 判定为误报的标准与各工具的抑制写法见 references/04-fix-workflow.md。

决策路由表（按需读对应 reference，勿全量加载）

使用流程

1. 第 0 步环境探测：构建工具 + JDK + 是否已配质量插件；已配则复用，未配走技能自带规则集。
2. 接入：默认建 .qualitygate/ 零侵入包装工程（读 references/01-setup.md）。
3. 实跑扫描：先编译，再跑 PMD 与 SpotBugs(FindSecBugs)，产出 XML 报告。
4. 按严重级修复：Blocker→Critical→Major 顺序（读 references/04-fix-workflow.md 做分级），修复手法查 02/03 速查表。
5. 复扫收敛：直到 Blocker/Critical 清零；同一告警 2 轮不消 → 说明并申请豁免。
6. 询问持久化：通过后问一次是否把插件写进项目 pom，拒绝则保持零侵入。