@comate/zulu 1.4.0-beta.2 → 1.4.0-beta.3

package/comate-engine/assets/skills/code-review/references/rules/Java/JAVA_RESOURCE_CONCURRENCY_RULES.md

@@ -0,0 +1,220 @@
+# Java 资源并发类规则
+
+涵盖线程安全、资源泄漏、数据库操作、性能及接口鉴权问题。
+
+---
+
+## 一、并发与线程安全（11项）
+
+### RACE_JAVA_01. 非线程安全集合在多线程环境并发修改 [high]
+- **检测**：多线程共享 HashMap/ArrayList 并发修改，可能死循环（JDK7）、数据错乱、ConcurrentModificationException
+- **排除**：已用 ConcurrentHashMap/CopyOnWriteArrayList；有锁保护
+
+### RACE_JAVA_02. SimpleDateFormat 多线程共享 [high]
+- **检测**：`static` 或 `@Service` 单例中的 `SimpleDateFormat` 成员变量被多线程共用
+- **排除**：已用 ThreadLocal；已改用 DateTimeFormatter（线程安全）
+
+### RACE_JAVA_03. 双重检查锁单例未用 volatile [high]
+- **检测**：DCL 单例 `instance` 字段缺少 `volatile`，可能因指令重排返回未完成初始化的对象
+
+```java
+private static Singleton instance; // 缺 volatile
+// 正确：private static volatile Singleton instance;
+```
+
+### RACE_JAVA_04. synchronized 锁对象选择不当 [Critical]
+- **检测**：
+  - 锁 String 常量池对象（`synchronized("lock")`）—— 不同类共享同一 String 常量，跨类互相阻塞
+  - 锁 Integer 缓存值（`synchronized(Integer.valueOf(n))`）—— -128~127 范围内对象被缓存共享
+  - 锁非 `private final` 对象 —— 字段可被外部替换，锁失效
+  - `synchronized(this.getClass())` —— 子类共享父类锁对象
+- **排除**：使用 `private final Object lock = new Object()`
+
+```java
+// 错误写法 — String 常量池共享
+synchronized ("myLock") { ... }
+
+// 错误写法 — 非 private final，可被外部替换
+public Object lock = new Object();
+synchronized (lock) { ... }
+
+// 正确写法
+private final Object lock = new Object();
+synchronized (lock) { ... }
+```
+
+### RACE_JAVA_05. 死锁导致线程挂起 [high]
+- **检测**：多线程加锁顺序不一致（线程1: A→B，线程2: B→A）形成循环等待
+- **排除**：固定加锁顺序；使用 tryLock 超时
+
+### RACE_JAVA_06. ConcurrentHashMap 复合操作非原子 [high]
+- **检测**：`if(!map.containsKey(k)) { map.put(k,v) }` 两步操作间有竞态
+- **排除**：已用 `computeIfAbsent`/`putIfAbsent`
+
+### RACE_JAVA_07. volatile 使用错误 [high]
+- **检测**：误以为 volatile 保证原子性（`volatile int count; count++` 仍非原子）；应用 volatile 保可见性却未用（stop flag 死循环）
+- **排除**：用 AtomicInteger 等原子类；volatile 仅用于可见性保证
+
+### RACE_JAVA_08. ThreadLocal 使用后未清理 [high]
+- **检测**：线程池中 ThreadLocal.set() 后无 remove()，线程复用时数据串用或内存泄漏
+- **排除**：在 finally/拦截器后置处理中有 remove()
+
+### RACE_JAVA_09. 线程池使用无界队列或无上限线程数 [high]
+- **检测**：`Executors.newFixedThreadPool`（无界队列）/`newCachedThreadPool`（无上限线程）；`new ThreadPoolExecutor(..., new LinkedBlockingQueue<>())` 无容量限制
+- **排除**：有界队列且容量合理；已用 ThreadPoolExecutor 显式配置
+
+### RACE_JAVA_10. Future.get() 未设置超时 [high]
+- **检测**：`future.get()` 无超时参数，远程任务挂起时线程永久阻塞，耗尽线程池
+- **排除**：已用 `future.get(timeout, unit)`
+
+### RACE_JAVA_11. @Async 注解失效 [middle]
+- **检测**：同类内部调用 @Async 方法（通过 this 调用，不经代理）；@Async 加在 private/final 方法上
+- **排除**：通过注入自身代理调用；从外部 Bean 调用
+
+---
+
+## 二、资源泄漏（6项）
+
+### RES_JAVA_01. 数据库连接未正确关闭 [high]
+- **检测**：Connection/Statement/ResultSet 未在 finally 或 try-with-resources 中关闭
+- **排除**：已用 try-with-resources；框架自动管理（Spring JdbcTemplate/MyBatis）
+
+### RES_JAVA_02. IO 流未关闭 [high]
+- **检测**：InputStream/OutputStream/Reader/Writer 未 close
+- **排除**：已用 try-with-resources
+
+### RES_JAVA_03. HTTP 连接未释放 [high]
+- **检测**：CloseableHttpResponse 未消费 entity 或未 close，连接无法归还连接池
+- **排除**：已用 try-with-resources + EntityUtils.consume
+
+### RES_JAVA_04. ReentrantLock 未在 finally 中 unlock [high]
+- **检测**：lock() 后无 try-finally 包裹，异常时锁永不释放导致死锁
+
+```java
+lock.lock();
+try { process(); } finally { lock.unlock(); } // 正确
+```
+
+### RES_JAVA_05. 本地缓存无限增长 OOM [high]
+- **检测**：静态 Map/List 只增不删，无容量限制/TTL/淘汰策略
+- **排除**：有 Guava Cache/Caffeine 等带淘汰策略的缓存；数量有界
+
+### RES_JAVA_06. ExecutorService 未 shutdown [middle]
+- **检测**：方法/类中创建的 ExecutorService 未调用 shutdown/shutdownNow，线程泄漏
+- **排除**：Spring 管理的 ThreadPoolTaskExecutor；有 shutdown 调用
+
+---
+
+## 三、数据库操作（5项）
+
+### DB_JAVA_01. N+1 查询 [middle]
+- **检测**：循环中对每条记录单独执行 SQL 查询
+- **排除**：已用 IN 批量查询；JOIN 查询；循环次数极少
+
+### DB_JAVA_02. 大批量数据操作未分批 [high]
+- **检测**：`selectAll()` 百万条数据一次加载到内存；批量 insert 无分批
+- **排除**：数据量确认有限；有分页/分批处理
+
+### DB_JAVA_03. Spring 事务失效 [high]
+- **检测**：同类内部方法调用 @Transactional 方法（不经代理）；@Transactional 加在 private 方法；catch 住异常未重新抛出导致事务不回滚
+- **排除**：通过代理 Bean 调用；有 @Transactional(rollbackFor=Exception.class) + 异常传播
+
+### DB_JAVA_04. 数据库免密连接 [Critical]
+- **检测**：JDBC URL 中 password 为空；无密码认证
+- **排除**：受信任的内网场景且有其他安全控制
+
+### DB_JAVA_05. 数据库密码明文硬编码 [Critical]
+- **检测**：源码中直接写死数据库密码字符串
+- **排除**：已从配置中心/KMS 获取；已加密存储
+
+---
+
+## 四、性能（3项）
+
+### PERF_JAVA_01. 循环中字符串 + 拼接 [low]
+- **检测**：循环内 `result += item`，每次创建新 String 对象，应用 StringBuilder
+- **排除**：循环次数极少（<10）
+
+### PERF_JAVA_02. 正则表达式灾难性回溯 ReDoS [high]
+- **检测**：`(a+)+`、`(a|aa)+` 等嵌套量词匹配长字符串，CPU 耗尽
+- **排除**：输入长度有限制；正则已优化
+
+### PERF_JAVA_03. 循环中创建重量级对象 [middle]
+- **检测**：循环内 `new ObjectMapper()`/`new SimpleDateFormat()` 等代价高的对象每次新建
+- **排除**：已提取到循环外；已用静态/线程本地实例
+
+---
+
+## 五、效率与正确性补充（4项）
+
+### EFF_JAVA_01. 可并行的串行 Future.get() [middle]
+- **检测**：连续提交多个互不依赖的 `CompletableFuture` 或 `Future`，却串行调用各自的 `.get()` 阻塞等待，而非用 `CompletableFuture.allOf()` 并行等待
+- **排除**：后一个操作依赖前一个的返回值；操作间有顺序语义
+
+```java
+// 反例 — 串行阻塞，总耗时 = tA + tB
+CompletableFuture<User> userFuture = fetchUserAsync(uid);
+User user = userFuture.get();                   // 阻塞等待
+CompletableFuture<Config> cfgFuture = fetchConfigAsync();
+Config cfg = cfgFuture.get();                   // 再阻塞等待
+
+// 正例 — 并行，总耗时 = max(tA, tB)
+CompletableFuture<User> userFuture = fetchUserAsync(uid);
+CompletableFuture<Config> cfgFuture = fetchConfigAsync();
+CompletableFuture.allOf(userFuture, cfgFuture).join();
+User user = userFuture.get();
+Config cfg = cfgFuture.get();
+```
+
+### EFF_JAVA_02. 文件/资源存在性预检查（TOCTOU） [low]
+- **检测**：操作前先调用 `file.exists()`/`Files.exists()` 检查存在性，再执行实际操作，形成 check-then-act 竞态
+- **排除**：业务逻辑确实需要分支且不可用异常替代
+
+```java
+// 反例
+if (file.exists()) {
+    Files.readAllBytes(file.toPath());
+}
+
+// 正例
+try {
+    Files.readAllBytes(file.toPath());
+} catch (NoSuchFileException e) {
+    // 处理不存在
+}
+```
+
+### EFF_JAVA_03. 正则校验缺少锚点 [middle]
+- **检测**：用于输入校验的正则表达式缺少 `^` 和 `$` 锚点，`Pattern.matcher(input).find()` 导致部分匹配通过本应拒绝的字符串
+- **排除**：明确需要部分匹配；已使用 `matches()` 方法（自带全串匹配语义）
+
+```java
+// 反例 — "123abc" 能通过纯数字校验
+Pattern.compile("\\d+").matcher(input).find();
+
+// 正例
+Pattern.compile("^\\d+$").matcher(input).matches();
+// 或直接用 String.matches()，它等价于全串匹配
+input.matches("\\d+");
+```
+
+### EFF_JAVA_04. 抛出异常时未保留原始异常（错误链断裂） [middle]
+- **检测**：在 `catch` 块中 `throw new XxxException("msg")` 时未将原始异常作为 `cause` 参数传入，导致原始堆栈信息丢失
+- **排除**：有意隐藏底层异常（安全场景）；原始异常已记录到日志
+
+```java
+// 反例 — 原始 cause 丢失
+try {
+    db.execute(sql);
+} catch (SQLException e) {
+    throw new ServiceException("数据库写入失败");  // e 丢失
+}
+
+// 正例
+try {
+    db.execute(sql);
+} catch (SQLException e) {
+    throw new ServiceException("数据库写入失败", e);
+}
+```
+

package/comate-engine/assets/skills/code-review/references/rules/Java/JAVA_STYLE_RULES.md

@@ -0,0 +1,306 @@
+# Java 代码风格扫描规则（共14条）
+
+---
+
+## 一、Import 规则（2项）
+
+### 1. JAVA010 UnusedImports - 未使用的 import 必须删除 [Critical]
+
+**缺陷描述**：所有未使用的 import 语句应该被删除。
+
+**判定方法**：在 import 声明之后的整个文件正文中（包括代码、注解、泛型参数），搜索该 import 引入的**简单类名**（最后一个 `.` 之后的部分）。如果该简单类名在文件正文中**从未以独立标识符形式出现**，则判定为未使用。
+
+**经典案例**：
+```java
+// 错误写法
+import java.util.HashMap;  // 文件中从未使用 HashMap
+import java.util.List;     // 文件中从未使用 List
+
+public class Example {
+    private String name;
+}
+```
+
+**注意 — 以下场景中 import 视为「已使用」，不应报告**：类名出现在类型声明、注解、泛型参数、Javadoc（`@see`/`@link`）、throws 子句、静态方法调用、instanceof 中。
+
+**核心原则：仅在确信类名在整个文件中完全不存在时才报告。如果无法确定，不报告。**
+
+---
+
+### 2. JAVA008 AvoidStarImport - 禁止通配符 import [Critical]
+
+**缺陷描述**：非 static 的 import 语句，禁止使用通配符（`*`）导入。
+
+**经典案例**：
+```java
+// 错误写法
+import java.util.*;
+import com.baidu.service.*;
+
+// 正确写法
+import java.util.List;
+import java.util.Map;
+```
+
+**不应报告的场景**：`import static org.junit.Assert.*` 等 static import 不受此规则限制。
+
+---
+
+## 二、命名规则（3项）
+
+### 3. JAVA028 MethodName - 方法名必须小驼峰 [Critical]
+
+**缺陷描述**：方法名必须以小写字母开头，遵循驼峰命名方式，匹配正则 `^[a-z][a-zA-Z0-9]*$`。
+
+**经典案例**：
+```java
+// 错误写法
+public void GetUserName() {}   // Pascal 风格
+public void get_user_name() {} // 蛇形命名
+public void _init() {}         // 下划线开头
+
+// 正确写法
+public void getUserName() {}
+public void init() {}
+```
+
+**不应报告的场景**：`@Test` 注解标记的测试方法；`@Override` 覆写父类/框架方法。
+
+---
+
+### 4. JAVA029 ConstantName - 常量命名必须全大写下划线分隔 [Critical]
+
+**缺陷描述**：`static final` 修饰的基本类型或 String 字段（常量）命名全部大写，单词间用下划线隔开。
+
+**「常量」判定标准**：同时满足：① `static final` 修饰；② 类型为基本数据类型或 String；③ 字段名不是 `serialVersionUID`。
+
+**经典案例**：
+```java
+// 错误写法
+public static final String max_count = "100";
+public static final int defaultSize = 10;
+
+// 正确写法
+public static final String MAX_COUNT = "100";
+public static final int DEFAULT_SIZE = 10;
+```
+
+**不应报告的场景**：Logger 对象、集合类型、工具对象、非 static 的 final 字段、枚举值、`serialVersionUID`（均不属于「常量」）。
+
+---
+
+### 5. JAVA032 PackageName - 包名只允许小写字母和数字 [Critical]
+
+**缺陷描述**：包名统一使用小写，每个 `.` 分隔的片段只包含小写字母 `[a-z]` 和数字 `[0-9]`。
+
+**经典案例**：
+```java
+// 错误写法
+package com.baidu.UserService;
+package com.baidu.user_service;
+
+// 正确写法
+package com.baidu.userservice;
+package org.apache.logging.log4j;
+```
+
+---
+
+## 三、格式规则（5项）
+
+### 6. JAVA018 LineLength - 单行不超过120字符 [Critical]
+
+**缺陷描述**：单行字符数不超过 120 个字符，超出需要换行。Tab 按 1 个字符计算。
+
+**豁免场景**：package 语句；import 语句；包含 URL 的行；单行字符串字面量。
+
+---
+
+### 7. JAVA003 FileTabCharacter - 禁止使用 Tab 字符 [Critical]
+
+**缺陷描述**：缩进必须使用空格而不是 Tab（ASCII 0x09）。
+
+**不应报告的场景**：字符串字面量内部的 `\t` 转义序列；无法确定是 Tab 还是空格时不报告。
+
+---
+
+### 8. JAVA014 LeftCurly - 左花括号遵循 K&R 风格 [Critical]
+
+**缺陷描述**：左花括号 `{` 不单独另起一行，放在前一语句的行末（K&R 风格）。
+
+**经典案例**：
+```java
+// 错误写法（Allman 风格）
+public class Example
+{
+    public void method()
+    {
+        if (condition)
+        {
+            doSomething();
+        }
+    }
+}
+
+// 正确写法（K&R 风格）
+public class Example {
+    public void method() {
+        if (condition) {
+            doSomething();
+        }
+    }
+}
+```
+
+**不应报告的场景**：空代码块 `{}` 可直接使用。
+
+---
+
+### 9. JAVA068 NeedBraces - if/else/for/while/do 必须使用花括号 [Critical]
+
+**缺陷描述**：`if`、`else`、`for`、`while`、`do` 语句中即使只有一行代码也必须使用花括号。
+
+**经典案例**：
+```java
+// 错误写法
+if (condition) doSomething();
+for (int i = 0; i < 10; i++) count++;
+
+// 正确写法
+if (condition) {
+    doSomething();
+}
+for (int i = 0; i < 10; i++) {
+    count++;
+}
+```
+
+**不应报告的场景**：Lambda 表达式；switch-case 语句。
+
+---
+
+### 10. JAVA020 WhitespaceAround - 关键字和运算符周围空格 [Critical]
+
+**缺陷描述**：以下位置必须加空格：① `if`/`for`/`while`/`switch` 等关键字与括号之间；② 左花括号 `{` 之前；③ 二元和三元运算符两边；④ 逗号后。
+
+**经典案例**：
+```java
+// 错误写法
+if(condition){}
+int result=a+b;
+method(a,b,c);
+
+// 正确写法
+if (condition) {}
+int result = a + b;
+method(a, b, c);
+```
+
+**核心原则：仅对上述 4 个场景中最明显的违规进行报告。对于不确定或边界情况，不报告。**
+
+---
+
+## 四、结构规则（1项）
+
+### 11. JAVA013 OverloadMethodsDeclarationOrder - 重载方法必须相邻 [Critical]
+
+**缺陷描述**：同名的构造函数或方法之间禁止插入其他成员，重载方法必须放在一起。
+
+**经典案例**：
+```java
+// 错误写法
+public class Example {
+    public void process(String s) {}
+    public void handle() {}          // 插入了其他方法
+    public void process(int n) {}    // 与上面的 process 被隔开
+}
+
+// 正确写法
+public class Example {
+    public void process(String s) {}
+    public void process(int n) {}    // 紧跟同名方法
+    public void handle() {}
+}
+```
+
+**不应报告的场景**：内部类中的同名方法与外部类独立判断；不同名方法之间的顺序不受约束。
+
+---
+
+## 五、注释规则（1项）
+
+### 12. JAVA070 CommentsMustBeJavadocInSomeCase - 类/属性/方法注释必须用 Javadoc [Critical]
+
+**缺陷描述**：类、public/protected 字段、public/protected 方法的注释必须使用 `/** 内容 */` 格式，不得使用 `// xxx` 方式。
+
+**经典案例**：
+```java
+// 错误写法
+// 用户服务类
+public class UserService {}
+
+// 错误写法
+// 创建订单
+public Order createOrder(OrderDTO dto) {}
+
+// 正确写法
+/** 用户服务类 */
+public class UserService {}
+
+/** 创建订单 */
+public Order createOrder(OrderDTO dto) {}
+```
+
+**不应报告的场景**：方法体内部的行间注释；private 成员注释；行尾注释；无注释的类/字段/方法（此规则只检查格式，不检查是否有注释）。
+
+---
+
+## 六、编程实践规则（2项）
+
+### 13. JAVA044 ObjectEquals - equals 方法防空指针 [Critical]
+
+**缺陷描述**：`Object.equals()` 方法容易抛空指针异常，应使用常量或确定有值的对象来调用 equals（字面量放左侧），或使用 `Objects.equals()`。
+
+**判定方法**：检查 **变量在左、字符串字面量在右** 的 `.equals(字面量)` 模式。
+
+**经典案例**：
+```java
+// 错误写法
+if (name.equals("admin")) {}
+if (status.equals("SUCCESS")) {}
+
+// 正确写法
+if ("admin".equals(name)) {}
+if (Objects.equals(status, "SUCCESS")) {}
+```
+
+**不应报告的场景**：字面量已在左侧；使用 `Objects.equals`；两侧都是变量（`a.equals(b)`）；枚举类型比较。
+
+**核心原则：只报告「变量.equals(字符串字面量)」的明确模式，其余情况不报告。**
+
+---
+
+### 14. JAVA041 OverrideWithAnnotation - 覆写方法必须加 @Override [Critical]
+
+**缺陷描述**：所有覆写方法必须加 `@Override` 注解，防止方法签名拼写错误时编译器不报错。
+
+**经典案例**：
+```java
+// 错误写法
+public class User {
+    public String toString() { return "User{" + name + "}"; }  // 缺少 @Override
+    public boolean equals(Object o) { return this == o; }       // 缺少 @Override
+}
+
+// 正确写法
+public class User {
+    @Override
+    public String toString() { return "User{" + name + "}"; }
+    @Override
+    public boolean equals(Object o) { return this == o; }
+}
+```
+
+**不应报告的场景**：类没有 extends/implements 且方法名不是 Object 的标准方法；无法从当前文件确定是否为覆写方法。
+
+**核心原则：只报告能高度确信是覆写方法（toString/equals/hashCode/clone/finalize，或有 super 调用）且缺少 @Override 的情况。**

package/comate-engine/assets/skills/code-review/references/rules/Js/JS_AUTH_RULES.md

@@ -0,0 +1,48 @@
+# 接口鉴权与越权检测规则
+
+本文件检测对外暴露接口的鉴权缺失与越权访问风险。适用于 JS/TS Node.js 后端服务。
+
+---
+
+### AUTH_01. 对外接口缺少鉴权 [high]
+- **检测**：有路由定义（router.get/post/put/delete）但无身份校验（req.user/req.session/ctx.user 校验）且无鉴权中间件（auth/authenticate/jwt/passport）
+- **排除**：健康检查（/health/ping/status）、登录注册、静态资源、Swagger、Webhook 回调、全局中间件统一鉴权
+- **复核**：确认无全局 auth 中间件；确认非公开接口
+
+### AUTH_02. 越权访问 - 未校验资源归属 [high]
+- **检测**：接口能获取用户身份（req.user），但操作资源时只用传入 ID（req.params.id/req.body.userId），未关联校验资源所有者
+- **排除**：管理员接口有角色校验；公共资源；ORM 关联查询间接校验
+- **复核**：确认能获取用户身份；确认未校验归属；确认非公共资源
+
+### AUTH_03. 身份校验逻辑错误 [high]
+- **检测**：用 `==` 而非 `===` 做 ID 比较；校验变量来自请求参数而非 token（req.params/query/body）；校验条件有赋值操作（`=` 代替 `==`）；校验位置在 early return 之后可被跳过
+- **排除**：校验逻辑有效；框架内置权限；中间件统一处理
+- **复核**：确认缺陷可被利用；确认变量来源错误
+
+```javascript
+// 错误写法 — 校验变量来自请求参数，可被伪造
+router.get('/orders/:id', (req, res) => {
+    const userId = req.params.userId;  // 来自请求，不可信
+    if (order.userId === userId) { ... }
+});
+
+// 正确写法 — 从已验证的 token 中获取
+router.get('/orders/:id', authMiddleware, (req, res) => {
+    const userId = req.user.id;  // 来自解析后的 token
+    if (order.userId === userId) { ... }
+});
+```
+
+### AUTH_04. 鉴权中间件配置遗漏 [middle]
+- **检测**：有全局鉴权中间件但部分路由组未被覆盖；中间件只保护特定 HTTP 方法
+- **排除**：明确分开的公开/受保护路由文件；NestJS Guards 等框架统一鉴权
+- **复核**：确认中间件确实未覆盖
+
+### AUTH_05. 垂直越权 - 敏感操作缺少角色/权限校验 [high]
+- **检测**：删除用户/修改权限/导出数据等管理员级别操作，未校验 `req.user.role` 或权限标记，普通用户可执行
+- **排除**：有角色校验（admin/superuser）；框架级权限管理（RBAC 中间件）
+- **复核**：确认该操作需要特权；确认无权限校验
+
+---
+
+**通用排除**：健康检查/登录/静态资源/Webhook 回调；全局中间件统一鉴权；框架统一权限管理（NestJS Guards、Passport）