Format

/format Skill

对 Java 代码批量执行格式化（spotless + eclipse P3C-CodeStyle）。

触发场景

用户输入：

• /format —— 对整个项目跑 mvn spotless:apply
• /format <模块名> —— 对指定模块跑 mvn -pl <模块名> spotless:apply

<模块名> 可以是：

• 模块根路径（如 user-service）—— 直接定位该模块
• 模块内子目录（如 user-service/src/main/java/com/foo）—— 向上找最近的 pom.xml 定位所属模块
• 单个 .java 文件（如 user-service/src/main/java/Foo.java）—— 同上，定位到所属模块
• 绝对路径—— 自动转换为相对项目根路径

无论 <模块名> 指向多深，实际执行粒度都是模块级：对整个所属模块跑 spotless（spotless 有增量缓存，未变更文件近乎零成本）。

执行步骤

1. 使用 Bash 工具在项目根加载 helper 并解析参数：

   source .claude/hooks/lib/common.sh
   ensure_java_home || { warn_missing_java_home; exit 1; }
   
   PROJECT_ROOT="$(find_project_root)"
   cd "$PROJECT_ROOT"
   
   ARG="<用户传入的 path，可能为空>"
   if [[ -z "$ARG" ]]; then
     mvn -q -B spotless:apply
   else
     # 路径校验
     if [[ ! -e "$ARG" ]]; then
       echo "错误：路径不存在：$ARG"
       echo "提示：/format 只支持传入模块根、模块内的子目录或 .java 文件；"
       echo "     若想格式化整个项目，请直接使用 /format（不带参数）。"
       exit 1
     fi
     MOD="$(find_module_root "$ARG")" || {
       echo "错误：$ARG 不属于任何 Maven 模块（未找到 pom.xml）。"
       echo "提示：/format 只支持传入模块根、模块内的子目录或 .java 文件；"
       echo "     若想格式化整个项目，请直接使用 /format（不带参数）。"
       exit 1
     }
     # 若定位到的模块就是项目根，退化为全量（避免 -pl . 的行为差异）
     if [[ "$MOD" == "$PROJECT_ROOT" ]]; then
       mvn -q -B spotless:apply
     else
       REL="${MOD#$PROJECT_ROOT/}"
       mvn -q -B -pl "$REL" spotless:apply
     fi
   fi
   

2. 简要汇报是否成功；spotless 无违规时无输出，视为通过

与 hook 的关系

回合结束时 Stop hook 会自动跑 spotless:apply + pmd:pmd。本 skill 用于用户主动想批量格式化（如刚 rebase 完、贴了外部代码，或想只格式化某个模块）时使用。

注意

• 不要询问用户确认。格式化是修正性、确定性操作，无副作用
• spotless 直接写文件，不需要 Edit 工具介入
• 传模块名/子目录/单文件时，实际是对整个所属模块格式化，不做子目录粒度过滤
• 若传入项目聚合根，等同 /format（不带参数）全量执行
• 若路径不存在或向上找不到 pom.xml → 报错并结束
• 如果失败，提示用户检查 pom.xml 是否已包含 spotless-maven-plugin