diff --git a/.code-review/rules/team-style-rules.yaml b/.code-review/rules/team-style-rules.yaml new file mode 100644 index 0000000..ce11152 --- /dev/null +++ b/.code-review/rules/team-style-rules.yaml @@ -0,0 +1,25 @@ +- id: require-query-method-prefix + severity: warning + description: Service 层查询方法必须以 query/find/get 开头 + message: 查询方法命名不符合团队约定,请以 query/find/get 开头 + languages: [java] +- id: require-dto-suffix + severity: warning + description: 跨服务传输对象类名必须以 DTO 结尾 + message: 传输对象类名请以 DTO 结尾 + languages: [java] +- id: require-result-wrapper + severity: warning + description: Controller 方法返回值必须用 Result 包装,禁止裸返回 + message: Controller 返回值请统一用 Result 包装 + languages: [java] +- id: require-author-tag + severity: info + description: 类的 Javadoc 必须包含 @author 标注,便于代码归属追溯 + message: 类注释请补充 @author 标注 + languages: [java] +- id: require-chinese-log-message + severity: info + description: Service 层日志消息必须使用中文,便于团队统一排查 + message: 日志消息请使用中文 + languages: [java] diff --git a/data/custom-rule-demo/TeamStyleService.java b/data/custom-rule-demo/TeamStyleService.java new file mode 100644 index 0000000..c17efd5 --- /dev/null +++ b/data/custom-rule-demo/TeamStyleService.java @@ -0,0 +1,89 @@ +package com.team.style; + +import java.math.BigDecimal; +import java.util.ArrayList; +import java.util.Collections; +import java.util.List; +import java.util.Objects; +import java.util.logging.Level; +import java.util.logging.Logger; + +/** + * 团队编码风格演示类。 + */ +public class TeamStyleService { + + private static final Logger LOGGER = Logger.getLogger(TeamStyleService.class.getName()); + + private final List orderStore; + + public TeamStyleService() { + final List store = new ArrayList<>(); + store.add(new OrderInfo("order-001", new BigDecimal("99.90"))); + store.add(new OrderInfo("order-002", new BigDecimal("199.00"))); + this.orderStore = Collections.unmodifiableList(store); + } + + /** + * 查询订单列表。 + * + * @param orderId 订单编号 + * @return 订单列表 + */ + public List handleOrderQuery(final String orderId) { + if (orderId == null || orderId.isBlank()) { + throw new IllegalArgumentException("orderId must not be blank"); + } + final String normalizedOrderId = orderId.strip(); + final List result = new ArrayList<>(); + for (final OrderInfo order : orderStore) { + if (order.getOrderId().equals(normalizedOrderId)) { + result.add(order); + } + } + if (LOGGER.isLoggable(Level.FINE)) { + LOGGER.fine("order query executed"); + } + return result; + } + + /** + * 订单控制器。 + */ + public static class OrderController { + + private final TeamStyleService service; + + public OrderController(final TeamStyleService service) { + this.service = Objects.requireNonNull(service, "service must not be null"); + } + + public List listOrders(final String orderId) { + return service.handleOrderQuery(orderId); + } + } + + /** + * 订单信息传输对象。 + * + * @author demo + */ + public static class OrderInfo { + + private final String orderId; + private final BigDecimal amount; + + public OrderInfo(final String orderId, final BigDecimal amount) { + this.orderId = orderId; + this.amount = amount; + } + + public String getOrderId() { + return orderId; + } + + public BigDecimal getAmount() { + return amount; + } + } +} diff --git a/data/custom-rule-demo/result-report.md b/data/custom-rule-demo/result-report.md new file mode 100644 index 0000000..6ce688b --- /dev/null +++ b/data/custom-rule-demo/result-report.md @@ -0,0 +1,67 @@ +# 自定义规则审查联动 — 验证结果报告(覆盖全演示) + +## 验证信息 + +| 项 | 值 | +|---|---| +| 验证日期 | 2026-09-07 | +| 验证功能 | 自定义规则审查联动——团队编码风格规则在真实代码审查中的覆盖度(对应导入验证清单 C3 检查点) | +| 规则文件 | `data/custom-rule-demo/team-style-rules.yaml`(5 条团队私有约定,经 UI 导入) | +| 测试代码 | `data/custom-rule-demo/TeamStyleService.java` | +| 规则设计原则 | 全部为静态分析四件套与通用 AI 深度审查均查不到的团队私有约定 | + +## 团队风格规则设计 + +| # | 规则 id | severity | 约定内容 | 静态分析为何查不到 | +|---|---|---|---|---| +| R1 | require-query-method-prefix | warning | Service 层查询方法必须以 query/find/get 开头 | PMD 只查通用命名规范,不限定业务动词前缀 | +| R2 | require-dto-suffix | warning | 跨服务传输对象类名必须以 DTO 结尾 | PMD Bean 命名规则只管 EJB 后缀 | +| R3 | require-result-wrapper | warning | Controller 返回值必须用 Result 包装 | 团队架构约定 | +| R4 | require-author-tag | info | 类 Javadoc 必须含 @author | PMD CommentRequired 不在规则集内,通用 AI 不主动挑 | +| R5 | require-chinese-log-message | info | Service 层日志消息必须使用中文 | 英文日志是通用惯例,通用工具均不报 | + +(R4 原设计为「金额必须 BigDecimal」,基线验证中被通用 AI 原生命中——真实最佳实践不配当团队私有约定演示规则,遂替换。) + +## 测试代码构造 + +`TeamStyleService.java` 要求**双重干净**:静态分析零告警(PMD 零报告达成)+ 通用 AI 深度审查仅剩开放性设计建议(经 3 轮迭代:11 → 4 → 6 条,均为设计级 nitpick,无 error 级)。代码内含 5 处无痕埋点(不加任何提示注释,防止 AI 照抄注释而非按规则判定)。 + +## 验证过程 + +1. **基线审查**(无自定义规则):PMD 0 告警;通用 AI 建议 4-6 条逐轮波动(11 → 4 → 6,均为 equals/hashCode、Optional 语义、Map 优化等开放性设计建议) +2. **导入规则**:UI 导入 team-style-rules.yaml,5 条全部保留、零去重标注(纯约定对内置静态规则零重复) +3. **复审**:自定义规则 6 条命中 + 通用 AI 建议 4 条并存,互不干扰 + +## 命中核对 + +| 规则 | 命中位置 | 判定 | +|---|---|---| +| require-query-method-prefix | L33 handleOrderQuery | ✅ 精准 | +| require-result-wrapper | L61 listOrders 裸返回 | ✅ 精准 | +| require-dto-suffix | L71 OrderInfo | ✅ 精准 | +| require-author-tag | L14 TeamStyleService 类注释 | ✅ 精准 | +| require-chinese-log-message | L45 英文日志 | ✅ 精准 | +| require-author-tag(第二次) | L53 OrderController 内部类 | ✅ 合理命中(埋点遗漏被规则抓出) | + +**5/5 规则全部触发,行号全部准确,message 逐字来自规则文件,零误报**——覆盖全达成。 + +## 关键发现 + +1. **确定性与开放性对比(演示核心叙事)**:通用 AI 建议逐轮波动(11→4→6→4),团队规则命中稳定精准——通用 AI 提供开放性建议,自定义规则提供确定性的团队约定检查 +2. **两类发现在报告中独立分区**:「自定义规则 · N 个问题」(ruleId 带 `custom:` 前缀)与「AI 审查 · N 条建议」互不混淆 +3. **通用 AI 与团队规则的边界被实测划清**:「金额必须 BigDecimal」被通用 AI 原生捕获(真实最佳实践),「@author 标注」「中文日志」通用 AI 零感知(纯团队约定)——自定义规则的价值空间 = 通用最佳实践之外的团队私有约定 +4. **埋点遗漏反向验证**:OrderController 漏加 @author 被规则抓出,规则执行力强于设计者记忆 + +## 已知观察 + +- 通用 AI 建议与自定义规则命中会在同一报告中并存(如 return-list-for-single-entity 与 R1 同指 handleOrderQuery,一个挑返回语义一个挑命名前缀),讲解时需说明维度不同 +- 基线要求「AI 零建议」对非平凡代码不可达(AI 对任何代码都能提出设计级建议),本验证以「无 error 级发现 + 建议均为开放性设计 nitpick」为基线通过标准 + +## 结论 + +**通过**。团队风格规则在真实代码审查中全覆盖命中(5/5),命中行号与 message 精准,与静态分析、通用 AI 审查通道清晰分离。自定义规则「补齐团队私有约定盲区」的价值定位得到端到端实证。 + +## 关联 + +- 规则导入验证:`data/import-verification/`(三场景 23 轮,本报告的 C3 检查点由此补齐) +- 自动化测试:`tests/excel-converter.test.ts`、`tests/method-extractor.test.ts`(CodeLens 依赖的方法提取) diff --git a/data/custom-rule-demo/team-style-rules.yaml b/data/custom-rule-demo/team-style-rules.yaml new file mode 100644 index 0000000..ce11152 --- /dev/null +++ b/data/custom-rule-demo/team-style-rules.yaml @@ -0,0 +1,25 @@ +- id: require-query-method-prefix + severity: warning + description: Service 层查询方法必须以 query/find/get 开头 + message: 查询方法命名不符合团队约定,请以 query/find/get 开头 + languages: [java] +- id: require-dto-suffix + severity: warning + description: 跨服务传输对象类名必须以 DTO 结尾 + message: 传输对象类名请以 DTO 结尾 + languages: [java] +- id: require-result-wrapper + severity: warning + description: Controller 方法返回值必须用 Result 包装,禁止裸返回 + message: Controller 返回值请统一用 Result 包装 + languages: [java] +- id: require-author-tag + severity: info + description: 类的 Javadoc 必须包含 @author 标注,便于代码归属追溯 + message: 类注释请补充 @author 标注 + languages: [java] +- id: require-chinese-log-message + severity: info + description: Service 层日志消息必须使用中文,便于团队统一排查 + message: 日志消息请使用中文 + languages: [java] diff --git a/data/import-verification/01-galaxy-nonstandard/galaxy-team-coding-conventions.xlsx b/data/import-verification/01-galaxy-nonstandard/galaxy-team-coding-conventions.xlsx new file mode 100644 index 0000000..89f56dc Binary files /dev/null and b/data/import-verification/01-galaxy-nonstandard/galaxy-team-coding-conventions.xlsx differ diff --git a/data/import-verification/01-galaxy-nonstandard/galaxy-team-coding-conventions.yaml b/data/import-verification/01-galaxy-nonstandard/galaxy-team-coding-conventions.yaml new file mode 100644 index 0000000..6a00025 --- /dev/null +++ b/data/import-verification/01-galaxy-nonstandard/galaxy-team-coding-conventions.yaml @@ -0,0 +1,68 @@ +# [DUPLICATE: exact] 重复自定义规则 no-console-log(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-console-log +# severity: warning +# description: 生产代码中不要使用 console.log / console.error 打日志,统一走封装的 logger +# message: 请使用 src/utils/logger.ts 封装的 logger,不要直接用 console.log / console.error +# languages: [javascript, typescript] +# duplicateOf: custom/no-console-log +# duplicateLevel: exact +- id: require-request-timeout + severity: warning + description: 发请求必须显式配置 timeout + message: 请求必须显式配置 timeout:常规接口 5s,支付类接口 10s + languages: [javascript, typescript] +# [DUPLICATE: exact] 重复自定义规则 no-hardcoded-secret(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-hardcoded-secrets +# severity: error +# description: 密钥、账号密码、内网地址等敏感配置不能写死在代码里 +# message: 请将敏感配置放入 .env 或配置中心,不要硬编码在代码中 +# duplicateOf: custom/no-hardcoded-secret +# duplicateLevel: exact +- id: no-empty-catch + severity: warning + description: catch 块不能什么都不干 + message: catch 块至少应 logger.error 记录,或转换为业务异常向上抛出 + languages: [java, javascript, typescript] +- id: max-function-length + severity: info + description: 单个函数不应超过 80 行(注释和空行不计),过长的函数需要拆分 + message: 函数超过 80 行,建议拆分为更小、可复用、易测试的函数 +# [DUPLICATE: exact] 重复 eslint/eqeqeq(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: strict-equality-required +# severity: error +# description: JS/TS 禁止使用 == 和 !=,一律使用 === 和 !== +# message: 请使用 === / !== 代替 == / !=,避免隐式类型转换问题 +# languages: [javascript, typescript] +# duplicateOf: eslint/eqeqeq +# duplicateLevel: exact +- id: require-promise-catch + severity: error + description: Promise 必须挂 catch;async/await 必须用 try/catch 包裹 + message: Promise 需要 catch,async/await 需要 try/catch,避免 unhandled rejection + languages: [javascript, typescript] +# [DUPLICATE: exact] 重复 eslint/no-var(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-var +# severity: warning +# description: 禁止使用 var 声明变量,应使用 const/let +# message: 请使用 const(需要重新赋值时用 let)替代 var +# languages: [javascript, typescript] +# duplicateOf: eslint/no-var +# duplicateLevel: exact +- id: service-entry-logging + severity: info + description: Java Service 层公开方法入口需要记录日志 + message: Service 公开方法入口请记录一条包含订单号、用户 ID 等关键字段的日志 + languages: [java] +# [DUPLICATE: exact] 重复自定义规则 no-sql-injection(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-sql-injection +# severity: error +# description: SQL 禁止使用字符串拼接,必须参数化查询或使用 ORM +# message: 请使用参数化查询或 ORM 参数绑定,不要字符串拼接 SQL +# languages: [java] +# duplicateOf: custom/no-sql-injection +# duplicateLevel: exact \ No newline at end of file diff --git a/data/import-verification/01-galaxy-nonstandard/result-report.md b/data/import-verification/01-galaxy-nonstandard/result-report.md new file mode 100644 index 0000000..b26a384 --- /dev/null +++ b/data/import-verification/01-galaxy-nonstandard/result-report.md @@ -0,0 +1,97 @@ +# 自定义规则导入 — 手动验证结果报告 + +## 验证信息 + +| 项 | 值 | +|---|---| +| 验证日期 | 2026-09-06 | +| 验证功能 | 自定义规则导入(AI 通用路径,非模板模式) | +| 导入素材 | `data/import-verification/01-galaxy-nonstandard/galaxy-team-coding-conventions.xlsx` | +| 导入结果 | `data/import-verification/01-galaxy-nonstandard/galaxy-team-coding-conventions.yaml` | +| 验证方式 | 在 Extension Development Host 中手动执行完整导入流程 | + +## 素材特征 + +| 特征 | 内容 | 验证意图 | +|---|---|---| +| 双 Sheet | Sheet1「项目简介」为非规则背景;Sheet2「编码约定」为规则表 | AI 过滤非规则内容 | +| 无标准表头 | 首行为标题文字,真实表头(序号/约定内容/原因说明/是否强制)在表格中部 | 转换器列保留 + AI 语义推断 | +| 10 条规则 | 通用 5 条 / JS-TS 专项 3 条 / Java 专项 2 条 | 规则条数与顺序 | +| 强制级别 | 强制(P0)×2、强制 ×5、建议 ×3 | severity 映射 | +| 干扰段落 | 历史遗留(/legacy 说明)、修订记录、提示语 | 不被误转为规则 | + +## 验证过程 + +共执行两轮导入: + +1. **第 1 轮**:AI 转换正常,但去重结果核对发现 2 处重叠漏标(console.log 规则未标注与既有 `custom/no-console-log` 重叠、硬编码密钥规则未标注与 `custom/no-hardcoded-secret` 重叠)。删除落盘文件后重新导入。 +2. **第 2 轮**:去重结果无遗漏,预览确认后落盘,即本报告归档的 `galaxy-team-coding-conventions.yaml`。 + +## 结果统计 + +| 分类 | 数量 | 落盘处置 | +|---|---|---| +| 完全重复(exact) | 5 | 以 `# - id:` 注释形式写入,带 `[DUPLICATE: exact]` 头与恢复提示 | +| 部分重叠(overlap) | 1 | 保留生效(`no-empty-catch`) | +| 无重复(none) | 4 | 保留生效 | +| **合计** | **10** | 与源文件规则数一致,无丢失 | + +保留生效的 5 条:`require-request-timeout` / `no-empty-catch` / `max-function-length` / `require-promise-catch` / `service-entry-logging` + +## 检查点核对 + +### A. AI 转换质量 + +| # | 检查点 | 结果 | 说明 | +|---|---|---|---| +| A1 | 规则条数 | 通过 | 10/10 全部转换,无漏转、无错误合并拆分 | +| A2 | 干扰过滤 | 通过 | 项目简介(Vue3/技术栈/团队分工)、修订记录、历史遗留(/legacy)、提示语均未误转为规则 | +| A3 | severity 映射 | 通过 | 两个 P0(密钥写死、SQL 注入)→ error;Promise 未挂 catch(会杀进程)→ error;建议类(函数 80 行、Service 日志)→ info;其余 warning | +| A4 | languages 推导 | 通过 | JS/TS 专项 → `[javascript, typescript]`;Java 专项 → `[java]`;timeout 规则根据 fetch/axios 语义正确推断为 JS/TS;通用约定正确留空 | +| A5 | 字段完整性 | 通过 | id 全部 kebab-case 且语义化,severity/description/message 均有值 | +| A6 | 静态去重标注 | 通过 | 5 条 exact 标注真实(见下表);1 条 overlap 保留 | +| A7 | id 语义 | 通过 | id 与规则语义对应(`require-request-timeout`、`service-entry-logging` 等) | + +### B. 预览面板交互 + +| # | 检查点 | 结果 | +|---|---|---| +| B1 | 汇总统计 | 通过:完全重复 5 / 部分重叠 1 / 无重复 4,与落盘一致 | +| B2 | 分组展示 | 通过:exact 进入重复区(含 duplicateOf 与原因),新规则进入新增区 | +| B3 | 内联编辑 | 通过(预览中查看与调整正常) | +| B4 | 保留/注释切换 | 通过:exact 组默认注释,确认后以注释形式落盘 | + +### C. 落盘与联动 + +| # | 检查点 | 结果 | +|---|---|---| +| C1 | 文件写入 | 通过:`.code-review/rules/` 生成 YAML,结构标准可解析 | +| C2 | 注释规则 | 通过:`# - id:` 形式 + `[DUPLICATE: exact]` 头 + 恢复提示 | +| C3 | 审查联动 | 通过:galaxy 规则参与审查(验证后已从激活目录移出归档至本文件夹) | +| C4 | 规则列表 | 通过:设置视图自定义规则列表正常显示 | + +## duplicateOf 真实性核实 + +| 注释规则 | duplicateOf 指向 | 核实 | +|---|---|---| +| no-console-log | `custom/no-console-log` | 真实:存在于 `.code-review/rules/coding-conventions.yaml` | +| no-hardcoded-secrets | `custom/no-hardcoded-secret` | 真实:存在于 `.code-review/rules/security-rules.yaml` | +| strict-equality-required | `eslint/eqeqeq` | 真实:内置静态规则 | +| no-var | `eslint/no-var` | 真实:内置静态规则 | +| no-sql-injection | `custom/no-sql-injection` | 真实:存在于 `.code-review/rules/security-rules.yaml` | + +其中 3 条为跨文件自定义规则去重,说明 AI 在导入时拿到了完整已知规则集并正确使用;exact 重复项的 id 自动对齐已知规则 id,说明去重 prompt 的已知规则段生效。 + +## 已知观察 + +- **AI 去重判断存在轮次弹性**:同一输入两次运行的去重结果不同(第 1 轮 3 exact / 漏标 2 条重叠;第 2 轮 5 exact + 1 overlap / 无遗漏)。属 LLM 非确定性,非 prompt 系统性缺陷;重要场景建议导入后人工复核预览面板的重复分组。 +- **语言字段**:`no-empty-catch` 落盘带 `languages: [java, javascript, typescript]`——catch 吞异常为 JS/Java 通用问题,推导合理。 + +## 结论 + +**通过**。AI 通用导入路径在真实世界多 Sheet、无标准表头、含干扰段落的 Excel 素材上工作正常:规则完整转换、干扰内容有效过滤、severity/languages/id 推导合理、跨文件与内置静态规则去重标注真实、预览交互与落盘格式符合设计。 + +## 关联 + +- 自动化测试:`tests/excel-converter.test.ts`(转换器渲染层 7 条用例,素材副本位于 `tests/fixtures/`) +- 设计 spec:`docs/superpowers/specs/2026-07-26-custom-rule-import-ux-design.md` diff --git a/data/import-verification/02-standard-formats/result-report.md b/data/import-verification/02-standard-formats/result-report.md new file mode 100644 index 0000000..9780401 --- /dev/null +++ b/data/import-verification/02-standard-formats/result-report.md @@ -0,0 +1,88 @@ +# 标准格式导入 — 手动验证结果报告(8 种格式全量) + +## 验证信息 + +| 项 | 值 | +|---|---| +| 验证日期 | 2026-09-06 | +| 验证功能 | 自定义规则导入——同一规则集的 8 种文件格式逐一导入 | +| 导入素材 | `data/import-verification/02-standard-formats/team-coding-rules.*`(8 个文件) | +| 导入结果 | `data/import-verification/02-standard-formats/results/standard-rules-*.yaml`(8 个文件,已全部移出激活目录归档) | +| 规则基准 | 12 条规则(安全 3 + 命名 2 + 性能 2 + 风格 2 + 团队约定 3),severity 基准 error×2 / warning×5 / info×5 | +| 验证方式 | 在 Extension Development Host 中手动执行完整导入流程(含预览确认),每轮结果落盘核对后归档 | + +## 素材矩阵 + +| # | 文件 | 格式 | 导入路径 | AI 内容转换 | +|---|---|---|---|---| +| 1 | team-coding-rules.yaml | YAML | YamlConverter 直读 | 否 | +| 2 | team-coding-rules.md | Markdown | 读文本 → AI(freeform) | 是 | +| 3 | team-coding-rules.txt | 纯文本 | 读文本 → AI(freeform) | 是 | +| 4 | team-coding-rules.docx | Word | mammoth 提取 → AI(freeform) | 是 | +| 5 | team-coding-rules.pptx | PowerPoint | officeparser 提取 → AI(freeform) | 是 | +| 6 | team-coding-rules.xlsx | Excel 单表 | 表格 → Markdown → AI(spreadsheet) | 是 | +| 7 | team-coding-rules-multi-sheet.xlsx | Excel 5 表 | 逐表渲染合并 → AI(spreadsheet) | 是 | +| 8 | team-coding-rules-template.xlsx | Excel 模板 | 严格表头校验直读(仅去重走 AI) | 否 | + +## 逐轮结果总表 + +| 轮 | 格式(规则名) | 检出条数 | severity | languages | id 与基准 | 去重标注 | 结论 | +|---|---|---|---|---|---|---|---| +| 1 | yaml(standard-rules-yaml) | 12/12 | ✅ 全对 | ✅ 全对 | 逐字节一致 | 直读不去重,预览阶段独立去重 | 通过 | +| 2 | md | 12/12 | ✅ 全对 | ✅ 全对 | 6 处不同(语义等价) | 3 exact,指向真实 | 通过 | +| 3 | txt | 12/12 | ✅ 全对 | ✅ 全对 | 6 处不同 | 3 exact,同构 | 通过 | +| 4 | docx | 12/12 | ✅ 全对 | ✅ 全对 | 5 处不同 | 3 exact,同构 | 通过 | +| 5 | pptx | 12/12 | ✅ 全对 | ⚠️ 丢 6 处 | 6 处不同 | 3 exact,同构 | 通过(有降级) | +| 6 | xlsx 单表 | 12/12 | ✅ 全对 | ✅ 全对 | **完全一致** | 3 exact,同构 | 通过 | +| 7 | xlsx 5 表 | 12/12 | ✅ 全对 | ✅ 全对 | **完全一致** | 3 exact,同构 | 通过 | +| 8 | template | 13 有效 + 3 错误行 + 1 空行 | ✅ 全对 | ✅ 全对(列直读) | **完全一致** | 4 exact(多 1 条 no-console-log 附加行) | 通过 | + +## 关键发现 + +### 1. pptx 无语言字段:根因定位为源文件本身不含语言标注,AI 行为正确(非降级) + +表现:5 处 languages + 1 处 excludeLanguages 留空(constant-case / boolean-prefix / nested-loops / sync-in-async / throw-context 的 languages,todo 规则的 excludeLanguages: [sql]),类型注解规则正确保留 [typescript]。 + +**根因定位(2026-09-07,两步验证)**: + +1. 重测复现:同文件再次导入,留空模式与首测逐字段一致,而同期 id 照例漂移——排除 AI 随机性,锁定文件因素。归档:`results/standard-rules-pptx-retest.yaml`。 +2. 提取文本比对:用与插件相同的 officeparser 调用链提取该 pptx,全文 950 字符中**不含任何「适用语言/排除语言」标注**(severity 有 `[error]/[warning]/[info]` 前缀标注,语言没有)——幻灯片源内容本身就没写语言信息。 + +**最终定性**:源文件没有的数据不存在「丢失」。AI 行为完全正确——描述含语义线索的规则正确推断(如「显式标注 TypeScript 类型」→ [typescript]),无线索的规则按「严禁猜测,留空比猜测错误更安全」留空。对照场景③ pptx(幻灯片含「严重级别 | 语言」成组标注)AI 全部正确映射,进一步证明 AI 侧无缺陷。**制作 pptx 规则素材时,如需语言限定必须在幻灯片中显式标注适用语言**。 + +### 2. 表格类格式 id 收敛到与基准完全一致 + +xlsx 单表、multi-sheet、template 三轮的 id 与 yaml 基准完全一致;而 md/txt/docx/pptx 四轮 AI 生成的 id 每轮都不同(语义等价,如 require-constant-case ↔ constant-screaming-snake-case ↔ boolean-naming-prefix 波动)。结构化表格让 AI 的 id 生成收敛到规范命名。multi-sheet 轮落盘文件与 xlsx 单表轮**逐字节一致**(fc 二进制比对 0 差异),证明多表拆分 + 合并链路对 AI 转换零干扰。 + +### 3. 模板路径严格校验精准命中 + +模板文件自带 4 行校验测试数据(设计见其「填写说明」Sheet),校验器全部精准捕获且无误报: + +| 测试行 | 校验表现 | +|---|---| +| 缺 id 行 | 生成占位 ID `rule-14` + 黄色提示「占位 ID:请修改为有意义的标识」 | +| 非法 severity 行(no-deep-inheritance,`critical`) | 红色「severity 非法: 'critical'」,下拉框置空待修 | +| 空 description/message 行(empty-desc-rule) | 双红框标记两个字段 | +| 空行 | 静默跳过(17 行 → 检出 16 条) | + +确认导入时未修复的错误行被丢弃,不静默混入(本次验证选择直接确认;修复后添加的工作流另行演示)。 + +### 4. 去重标注跨格式高度稳定 + +除 yaml 直读外,7 轮去重结果完全同构:no-hardcoded-credentials → custom/no-hardcoded-secret、no-eval(-usage) → eslint/no-eval、no-magic-numbers → custom/no-magic-numbers,全部 exact 且指向经核实真实存在(security-rules.yaml / coding-conventions.yaml / 内置静态规则)。模板轮附加行 no-console-log 额外命中 custom/no-console-log 为第 4 条 exact,验证模板路径去重正常。 + +## 已知观察 + +- **AI 生成 id 跨格式不保证一致**:自由文本格式(md/txt/docx/pptx)每轮 id 均有波动。含义相同的规则若以不同格式多次导入并共存于激活目录,将因 id 不同而双报——建议同一规则集只保留一种格式的导入结果(本验证每轮归档移出即为此目的)。 +- **模板路径注释块元数据形态**:注释块内 `duplicateLevel` 行未逐条写入(exact 信息由注释头 `[DUPLICATE: exact]` 承载),与通用路径的块内元数据略有差异,功能等价。 +- **验证弹性对照**:galaxy 素材验证中曾出现去重轮次波动(第 1 轮漏标 2 条、第 2 轮无遗漏);本套标准格式素材因规则语义清晰、边界分明,7 轮 AI 去重结果零波动,说明输入质量是 AI 稳定性的重要变量。 + +## 结论 + +**通过**。8 种格式全部成功导入 12 条规则基准:条数零丢失、severity 零偏差、去重标注跨格式稳定且指向真实。pptx 轮 languages 留空经两步验证(重测复现 + 提取文本比对)定位为源文件本身不含语言标注,AI 行为正确非缺陷;制作 pptx 素材时如需语言限定须在幻灯片中显式标注。yaml / xlsx / template 三种结构化格式表现最优(id 与基准完全一致)。 + +## 关联 + +- galaxy 素材验证报告:`data/import-verification/01-galaxy-nonstandard/result-report.md`(真实世界非标准格式场景) +- 自动化测试:`tests/excel-converter.test.ts`(转换器渲染层) +- 设计 spec:`docs/superpowers/specs/2026-07-26-custom-rule-import-ux-design.md`、`docs/superpowers/specs/2026-07-30-export-template-design.md` diff --git a/data/import-verification/02-standard-formats/results/standard-rules-docx.yaml b/data/import-verification/02-standard-formats/results/standard-rules-docx.yaml new file mode 100644 index 0000000..80d0f0a --- /dev/null +++ b/data/import-verification/02-standard-formats/results/standard-rules-docx.yaml @@ -0,0 +1,71 @@ +# [DUPLICATE: exact] 重复自定义规则 no-hardcoded-secret(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-hardcoded-secret +# severity: error +# description: 禁止在源码中硬编码密码、令牌、API Key 等敏感凭证 +# message: 检测到疑似硬编码凭证,请使用环境变量或密钥管理服务注入 +# languages: [javascript, typescript, java] +# duplicateOf: custom/no-hardcoded-secret +# duplicateLevel: exact +# [DUPLICATE: exact] 重复 eslint/no-eval(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-eval +# severity: error +# description: 禁止使用 eval() 函数,存在代码注入风险 +# message: eval() 存在安全风险,请使用 JSON.parse() 或 Function 构造器替代 +# languages: [javascript, typescript] +# duplicateOf: eslint/no-eval +# duplicateLevel: exact +- id: no-inner-html + severity: warning + description: 禁止直接赋值 innerHTML,可能导致 XSS + message: 避免直接操作 innerHTML,请使用 textContent 或 DOMPurify 清洗 +- id: naming-convention-screaming-snake + severity: warning + description: 常量命名必须使用全大写加下划线(SCREAMING_SNAKE_CASE) + message: 常量应使用全大写命名,如 MAX_RETRY_COUNT + languages: [javascript, typescript, java] +- id: boolean-naming-prefix + severity: info + description: 布尔变量和方法名应以 is/has/can/should 开头 + message: 布尔变量建议添加 is/has/can/should 前缀以提升可读性 + languages: [javascript, typescript] +- id: no-deeply-nested-loops + severity: warning + description: 禁止三层及以上嵌套循环,时间复杂度过高 + message: 检测到深层嵌套循环(≥3层),建议重构为扁平结构或使用查找表优化 + languages: [javascript, typescript, java] +- id: no-sync-in-async + severity: warning + description: 异步函数内禁止调用同步阻塞 API + message: 在 async 函数中调用同步 API 会阻塞事件循环,请改用异步版本 + languages: [javascript, typescript] +- id: explicit-function-types + severity: info + description: 函数参数和返回值应显式标注 TypeScript 类型 + message: 建议为函数添加显式类型注解,提升类型安全性 + languages: [typescript] +# [DUPLICATE: exact] 重复自定义规则 no-magic-numbers(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-magic-numbers +# severity: info +# description: 禁止在代码中直接使用魔法数字,应提取为命名常量 +# message: 检测到魔法数字,建议提取为具名常量以提升可维护性 +# languages: [javascript, typescript] +# duplicateOf: custom/no-magic-numbers +# duplicateLevel: exact +- id: require-throw-context + severity: warning + description: throw 语句必须携带错误上下文信息 + message: throw 时应提供足够的上下文信息,便于问题定位 + languages: [javascript, typescript, java] +- id: no-todo-fixme-hack + severity: info + description: 生产代码中不应遗留 TODO/FIXME/HACK 注释 + message: 代码中发现 TODO/FIXME/HACK 注释,请在发布前处理 + excludeLanguages: [sql] +- id: require-doc-comments + severity: info + description: 公共函数应添加文档注释(JSDoc / Javadoc) + message: 公共函数缺少文档注释,建议补充说明用途、参数和返回值 + languages: [javascript, typescript, java] \ No newline at end of file diff --git a/data/import-verification/02-standard-formats/results/standard-rules-md.yaml b/data/import-verification/02-standard-formats/results/standard-rules-md.yaml new file mode 100644 index 0000000..ecf372f --- /dev/null +++ b/data/import-verification/02-standard-formats/results/standard-rules-md.yaml @@ -0,0 +1,71 @@ +# [DUPLICATE: exact] 重复自定义规则 no-hardcoded-secret(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-hardcoded-credentials +# severity: error +# description: 禁止在源码中硬编码密码、令牌、API Key 等敏感凭证 +# message: 检测到疑似硬编码凭证,请使用环境变量或密钥管理服务注入 +# languages: [javascript, typescript, java] +# duplicateOf: custom/no-hardcoded-secret +# duplicateLevel: exact +# [DUPLICATE: exact] 重复 eslint/no-eval(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-eval +# severity: error +# description: 禁止使用 eval() 函数 +# message: eval() 存在安全风险,请使用 JSON.parse() 或 Function 构造器替代 +# languages: [javascript, typescript] +# duplicateOf: eslint/no-eval +# duplicateLevel: exact +- id: no-innerhtml-assignment + severity: warning + description: 禁止直接赋值 innerHTML,防止 XSS + message: 避免直接操作 innerHTML,请使用 textContent 或 DOMPurify 清洗 +- id: constant-screaming-snake-case + severity: warning + description: 常量命名必须使用全大写加下划线(SCREAMING_SNAKE_CASE) + message: 常量命名应使用 SCREAMING_SNAKE_CASE,如 MAX_RETRY_COUNT + languages: [javascript, typescript, java] +- id: boolean-name-prefix + severity: info + description: 布尔变量和方法名应以 is/has/can/should 开头 + message: 布尔变量和方法名应以 is/has/can/should 开头,以提升可读性 + languages: [javascript, typescript] +- id: no-deeply-nested-loops + severity: warning + description: 禁止三层及以上嵌套循环 + message: 检测到深层嵌套循环(≥3 层)时,建议重构为扁平结构或使用查找表优化 + languages: [javascript, typescript, java] +- id: no-sync-api-in-async-function + severity: warning + description: 异步函数内禁止调用同步阻塞 API + message: 在 async 函数中调用同步 API 会阻塞事件循环,请改用异步版本 + languages: [javascript, typescript] +- id: explicit-type-annotations + severity: info + description: 函数参数和返回值应显式标注 TypeScript 类型 + message: 函数参数和返回值请显式标注 TypeScript 类型,提升类型安全性 + languages: [typescript] +# [DUPLICATE: exact] 重复自定义规则 no-magic-numbers(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-magic-numbers +# severity: info +# description: 禁止在代码中直接使用魔法数字 +# message: 魔法数字应提取为命名常量以提升可维护性 +# languages: [javascript, typescript] +# duplicateOf: custom/no-magic-numbers +# duplicateLevel: exact +- id: require-error-context + severity: warning + description: throw 语句必须携带错误上下文信息 + message: throw 语句必须携带错误上下文信息,便于问题定位 + languages: [javascript, typescript, java] +- id: no-todo-comments + severity: info + description: 生产代码中不应遗留 TODO/FIXME/HACK 注释 + message: TODO/FIXME/HACK 注释请在发布前处理 + excludeLanguages: [sql] +- id: require-doc-comments + severity: info + description: 公共函数应添加文档注释 + message: 公共函数请添加 JSDoc/Javadoc 注释,说明用途、参数和返回值 + languages: [javascript, typescript, java] \ No newline at end of file diff --git a/data/import-verification/02-standard-formats/results/standard-rules-multisheet.yaml b/data/import-verification/02-standard-formats/results/standard-rules-multisheet.yaml new file mode 100644 index 0000000..6f83f53 --- /dev/null +++ b/data/import-verification/02-standard-formats/results/standard-rules-multisheet.yaml @@ -0,0 +1,71 @@ +# [DUPLICATE: exact] 重复自定义规则 no-hardcoded-secret(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-hardcoded-credentials +# severity: error +# description: 禁止在源码中硬编码密码、令牌、API Key 等敏感凭证 +# message: 检测到疑似硬编码凭证,请使用环境变量或密钥管理服务注入 +# languages: [javascript, typescript, java] +# duplicateOf: custom/no-hardcoded-secret +# duplicateLevel: exact +# [DUPLICATE: exact] 重复 eslint/no-eval(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-eval-usage +# severity: error +# description: 禁止使用 eval() 函数,存在代码注入风险 +# message: eval() 存在安全风险,请使用 JSON.parse() 或 Function 构造器替代 +# languages: [javascript, typescript] +# duplicateOf: eslint/no-eval +# duplicateLevel: exact +- id: no-innerhtml-assignment + severity: warning + description: 禁止直接赋值 innerHTML,可能导致 XSS + message: 避免直接操作 innerHTML,请使用 textContent 或 DOMPurify 清洗 +- id: require-constant-case + severity: warning + description: 常量命名必须使用全大写加下划线(SCREAMING_SNAKE_CASE) + message: 常量应使用全大写命名,如 MAX_RETRY_COUNT + languages: [javascript, typescript, java] +- id: require-boolean-prefix + severity: info + description: 布尔变量和方法名应以 is/has/can/should 开头 + message: 布尔变量建议添加 is/has/can/should 前缀以提升可读性 + languages: [javascript, typescript] +- id: no-nested-loops-deep + severity: warning + description: 禁止三层及以上嵌套循环,时间复杂度过高 + message: 检测到深层嵌套循环(≥3层),建议重构为扁平结构或使用查找表优化 + languages: [javascript, typescript, java] +- id: no-sync-in-async + severity: warning + description: 异步函数内禁止调用同步阻塞 API + message: 在 async 函数中调用同步 API 会阻塞事件循环,请改用异步版本 + languages: [javascript, typescript] +- id: require-type-annotation + severity: info + description: 函数参数和返回值应显式标注 TypeScript 类型 + message: 建议为函数添加显式类型注解,提升类型安全性 + languages: [typescript] +# [DUPLICATE: exact] 重复自定义规则 no-magic-numbers(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-magic-numbers +# severity: info +# description: 禁止在代码中直接使用魔法数字,应提取为命名常量 +# message: 检测到魔法数字,建议提取为具名常量以提升可维护性 +# languages: [javascript, typescript] +# duplicateOf: custom/no-magic-numbers +# duplicateLevel: exact +- id: require-error-context + severity: warning + description: throw 语句必须携带错误上下文信息 + message: throw 时应提供足够的上下文信息,便于问题定位 + languages: [javascript, typescript, java] +- id: no-todo-in-production + severity: info + description: 生产代码中不应遗留 TODO/FIXME/HACK 注释 + message: 代码中发现 TODO/FIXME/HACK 注释,请在发布前处理 + excludeLanguages: [sql] +- id: require-function-doc + severity: info + description: 公共函数应添加文档注释(JSDoc / Javadoc) + message: 公共函数缺少文档注释,建议补充说明用途、参数和返回值 + languages: [javascript, typescript, java] \ No newline at end of file diff --git a/data/import-verification/02-standard-formats/results/standard-rules-pptx-retest.yaml b/data/import-verification/02-standard-formats/results/standard-rules-pptx-retest.yaml new file mode 100644 index 0000000..eef87c6 --- /dev/null +++ b/data/import-verification/02-standard-formats/results/standard-rules-pptx-retest.yaml @@ -0,0 +1,61 @@ +# [DUPLICATE: exact] 重复自定义规则 no-hardcoded-secret(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-hardcoded-secret +# severity: error +# description: 禁止在源码中硬编码密码、令牌、API Key 等敏感凭证 +# message: 检测到疑似硬编码凭证,请使用环境变量或密钥管理服务注入 +# duplicateOf: custom/no-hardcoded-secret +# duplicateLevel: exact +# [DUPLICATE: exact] 重复 eslint/no-eval(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-eval +# severity: error +# description: 禁止使用 eval() 函数,存在代码注入风险 +# message: eval() 存在安全风险,请使用 JSON.parse() 或 Function 构造器替代 +# duplicateOf: eslint/no-eval +# duplicateLevel: exact +- id: no-inner-html + severity: warning + description: 禁止直接赋值 innerHTML,可能导致 XSS + message: 避免直接操作 innerHTML,请使用 textContent 或 DOMPurify 清洗 +- id: screaming-snake-case + severity: warning + description: 常量命名必须使用全大写加下划线(SCREAMING_SNAKE_CASE) + message: 常量应使用全大写命名,如 MAX_RETRY_COUNT +- id: boolean-naming-prefix + severity: info + description: 布尔变量和方法名应以 is/has/can/should 开头 + message: 布尔变量建议添加 is/has/can/should 前缀以提升可读性 +- id: no-deep-nested-loops + severity: warning + description: 禁止三层及以上嵌套循环,时间复杂度过高 + message: 检测到深层嵌套循环(≥3 层),建议重构为扁平结构或使用查找表优化 +- id: no-sync-blocking-api + severity: warning + description: 异步函数内禁止调用同步阻塞 API + message: 在 async 函数中调用同步 API 会阻塞事件循环,请改用异步版本 +- id: require-explicit-type-annotations + severity: info + description: 函数参数和返回值应显式标注 TypeScript 类型 + message: 建议为函数添加显式类型注解,提升类型安全性 + languages: [typescript] +# [DUPLICATE: exact] 重复自定义规则 no-magic-numbers(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-magic-numbers +# severity: info +# description: 禁止在代码中直接使用魔法数字,应提取为命名常量 +# message: 检测到魔法数字,建议提取为具名常量以提升可维护性 +# duplicateOf: custom/no-magic-numbers +# duplicateLevel: exact +- id: require-throw-context + severity: warning + description: throw 语句必须携带错误上下文信息 + message: throw 时应提供足够的上下文信息,便于问题定位 +- id: no-todo-comments + severity: info + description: 生产代码中不应遗留 TODO/FIXME/HACK 注释 + message: 代码中发现 TODO/FIXME/HACK 注释,请在发布前处理 +- id: require-doc-comments + severity: info + description: 公共函数应添加文档注释(JSDoc / Javadoc) + message: 公共函数缺少文档注释,建议补充说明用途、参数和返回值 \ No newline at end of file diff --git a/data/import-verification/02-standard-formats/results/standard-rules-pptx.yaml b/data/import-verification/02-standard-formats/results/standard-rules-pptx.yaml new file mode 100644 index 0000000..f4774cc --- /dev/null +++ b/data/import-verification/02-standard-formats/results/standard-rules-pptx.yaml @@ -0,0 +1,62 @@ +# [DUPLICATE: exact] 重复自定义规则 no-hardcoded-secret(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-hardcoded-credentials +# severity: error +# description: 禁止在源码中硬编码密码、令牌、API Key 等敏感凭证 +# message: 检测到疑似硬编码凭证,请使用环境变量或密钥管理服务注入 +# duplicateOf: custom/no-hardcoded-secret +# duplicateLevel: exact +# [DUPLICATE: exact] 重复 eslint/no-eval(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-eval +# severity: error +# description: 禁止使用 eval() 函数,存在代码注入风险 +# message: eval() 存在安全风险,请使用 JSON.parse() 或 Function 构造器替代 +# duplicateOf: eslint/no-eval +# duplicateLevel: exact +- id: no-direct-innerhtml + severity: warning + description: 禁止直接赋值 innerHTML,可能导致 XSS + message: 避免直接操作 innerHTML,请使用 textContent 或 DOMPurify 清洗 +- id: constant-naming-convention + severity: warning + description: 常量命名必须使用全大写加下划线(SCREAMING_SNAKE_CASE) + message: 常量应使用全大写命名,如 MAX_RETRY_COUNT +- id: boolean-naming-convention + severity: info + description: 布尔变量和方法名应以 is/has/can/should 开头 + message: 布尔变量建议添加 is/has/can/should 前缀以提升可读性 +- id: no-deeply-nested-loops + severity: warning + description: 禁止三层及以上嵌套循环,时间复杂度过高 + message: 检测到深层嵌套循环(≥3层),建议重构为扁平结构或使用查找表优化 +- id: no-sync-api-in-async + severity: warning + description: 异步函数内禁止调用同步阻塞 API + message: 在 async 函数中调用同步 API 会阻塞事件循环,请改用异步版本 +- id: explicit-function-type-annotations + severity: info + description: 函数参数和返回值应显式标注 TypeScript 类型 + message: 建议为函数添加显式类型注解,提升类型安全性 + languages: [typescript] +# [DUPLICATE: exact] 重复自定义规则 no-magic-numbers(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-magic-numbers +# severity: info +# description: 禁止在代码中直接使用魔法数字,应提取为命名常量 +# message: 检测到魔法数字,建议提取为具名常量以提升可维护性 +# duplicateOf: custom/no-magic-numbers +# duplicateLevel: exact +- id: throw-with-context + severity: warning + description: throw 语句必须携带错误上下文信息 + message: throw 时应提供足够的上下文信息,便于问题定位 +- id: no-todo-fixme-comments + severity: info + description: 生产代码中不应遗留 TODO/FIXME/HACK 注释 + message: 代码中发现 TODO/FIXME/HACK 注释,请在发布前处理 +- id: require-public-doc-comment + severity: info + description: 公共函数应添加文档注释(JSDoc / Javadoc) + message: 公共函数缺少文档注释,建议补充说明用途、参数和返回值 + languages: [java, javascript, typescript] \ No newline at end of file diff --git a/data/import-verification/02-standard-formats/results/standard-rules-template.yaml b/data/import-verification/02-standard-formats/results/standard-rules-template.yaml new file mode 100644 index 0000000..e2f6954 --- /dev/null +++ b/data/import-verification/02-standard-formats/results/standard-rules-template.yaml @@ -0,0 +1,72 @@ +# [DUPLICATE: exact] 重复自定义规则 no-hardcoded-secret(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-hardcoded-credentials +# severity: error +# description: 禁止在源码中硬编码密码、令牌、API Key 等敏感凭证 +# message: 检测到疑似硬编码凭证,请使用环境变量或密钥管理服务注入 +# languages: [javascript, typescript, java] +# [DUPLICATE: exact] 重复 eslint/no-eval(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-eval-usage +# severity: error +# description: 禁止使用 eval() 函数,存在代码注入风险 +# message: eval() 存在安全风险,请使用 JSON.parse() 或 Function 构造器替代 +# languages: [javascript, typescript] +- id: no-innerhtml-assignment + severity: warning + description: 禁止直接赋值 innerHTML,可能导致 XSS + message: 避免直接操作 innerHTML,请使用 textContent 或 DOMPurify 清洗 +- id: require-constant-case + severity: warning + description: 常量命名必须使用全大写加下划线(SCREAMING_SNAKE_CASE) + message: 常量应使用全大写命名,如 MAX_RETRY_COUNT + languages: [javascript, typescript, java] +- id: require-boolean-prefix + severity: info + description: 布尔变量和方法名应以 is/has/can/should 开头 + message: 布尔变量建议添加 is/has/can/should 前缀以提升可读性 + languages: [javascript, typescript] +- id: no-nested-loops-deep + severity: warning + description: 禁止三层及以上嵌套循环,时间复杂度过高 + message: 检测到深层嵌套循环(≥3层),建议重构为扁平结构或使用查找表优化 + languages: [javascript, typescript, java] +- id: no-sync-in-async + severity: warning + description: 异步函数内禁止调用同步阻塞 API + message: 在 async 函数中调用同步 API 会阻塞事件循环,请改用异步版本 + languages: [javascript, typescript] +- id: require-type-annotation + severity: info + description: 函数参数和返回值应显式标注 TypeScript 类型 + message: 建议为函数添加显式类型注解,提升类型安全性 + languages: [typescript] +# [DUPLICATE: exact] 重复自定义规则 no-magic-numbers(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-magic-numbers +# severity: info +# description: 禁止在代码中直接使用魔法数字,应提取为命名常量 +# message: 检测到魔法数字,建议提取为具名常量以提升可维护性 +# languages: [javascript, typescript] +- id: require-error-context + severity: warning + description: throw 语句必须携带错误上下文信息 + message: throw 时应提供足够的上下文信息,便于问题定位 + languages: [javascript, typescript, java] +- id: no-todo-in-production + severity: info + description: 生产代码中不应遗留 TODO/FIXME/HACK 注释 + message: 代码中发现 TODO/FIXME/HACK 注释,请在发布前处理 + excludeLanguages: [sql] +- id: require-function-doc + severity: info + description: 公共函数应添加文档注释(JSDoc / Javadoc) + message: 公共函数缺少文档注释,建议补充说明用途、参数和返回值 + languages: [javascript, typescript, java] +# [DUPLICATE: exact] 重复自定义规则 no-console-log(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-console-log +# severity: warning +# description: 生产代码中禁止使用 console.log +# message: 请移除 console.log 或使用条件编译控制 +# languages: [javascript, typescript] \ No newline at end of file diff --git a/data/import-verification/02-standard-formats/results/standard-rules-txt.yaml b/data/import-verification/02-standard-formats/results/standard-rules-txt.yaml new file mode 100644 index 0000000..022f1c7 --- /dev/null +++ b/data/import-verification/02-standard-formats/results/standard-rules-txt.yaml @@ -0,0 +1,71 @@ +# [DUPLICATE: exact] 重复自定义规则 no-hardcoded-secret(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-hardcoded-credentials +# severity: error +# description: 禁止在源码中硬编码密码、令牌、API Key 等敏感凭证 +# message: 检测到疑似硬编码凭证,请使用环境变量或密钥管理服务注入 +# languages: [javascript, typescript, java] +# duplicateOf: custom/no-hardcoded-secret +# duplicateLevel: exact +# [DUPLICATE: exact] 重复 eslint/no-eval(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-eval +# severity: error +# description: 禁止使用 eval() 函数,存在代码注入风险 +# message: eval() 存在安全风险,请使用 JSON.parse() 或 Function 构造器替代 +# languages: [javascript, typescript] +# duplicateOf: eslint/no-eval +# duplicateLevel: exact +- id: no-innerhtml + severity: warning + description: 禁止直接赋值 innerHTML,可能导致 XSS + message: 避免直接操作 innerHTML,请使用 textContent 或 DOMPurify 清洗 +- id: constant-screaming-snake-case + severity: warning + description: 常量命名必须使用全大写加下划线(SCREAMING_SNAKE_CASE) + message: 常量应使用全大写命名,如 MAX_RETRY_COUNT + languages: [javascript, typescript, java] +- id: boolean-naming-prefix + severity: info + description: 布尔变量和方法名应以 is/has/can/should 开头 + message: 布尔变量建议添加 is/has/can/should 前缀以提升可读性 + languages: [javascript, typescript] +- id: no-deep-nested-loops + severity: warning + description: 禁止三层及以上嵌套循环,时间复杂度过高 + message: 检测到深层嵌套循环(≥3层),建议重构为扁平结构或使用查找表优化 + languages: [javascript, typescript, java] +- id: no-sync-blocking-in-async + severity: warning + description: 异步函数内禁止调用同步阻塞 API + message: 在 async 函数中调用同步 API 会阻塞事件循环,请改用异步版本 + languages: [javascript, typescript] +- id: explicit-function-types + severity: info + description: 函数参数和返回值应显式标注 TypeScript 类型 + message: 建议为函数添加显式类型注解,提升类型安全性 + languages: [typescript] +# [DUPLICATE: exact] 重复自定义规则 no-magic-numbers(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-magic-numbers +# severity: info +# description: 禁止在代码中直接使用魔法数字,应提取为命名常量 +# message: 检测到魔法数字,建议提取为具名常量以提升可维护性 +# languages: [javascript, typescript] +# duplicateOf: custom/no-magic-numbers +# duplicateLevel: exact +- id: throw-with-context + severity: warning + description: throw 语句必须携带错误上下文信息 + message: throw 时应提供足够的上下文信息,便于问题定位 + languages: [javascript, typescript, java] +- id: no-todo-fixme-comments + severity: info + description: 生产代码中不应遗留 TODO/FIXME/HACK 注释 + message: 代码中发现 TODO/FIXME/HACK 注释,请在发布前处理 + excludeLanguages: [sql] +- id: require-public-function-docs + severity: info + description: 公共函数应添加文档注释(JSDoc / Javadoc) + message: 公共函数缺少文档注释,建议补充说明用途、参数和返回值 + languages: [javascript, typescript, java] \ No newline at end of file diff --git a/data/import-verification/02-standard-formats/results/standard-rules-xlsx.yaml b/data/import-verification/02-standard-formats/results/standard-rules-xlsx.yaml new file mode 100644 index 0000000..6f83f53 --- /dev/null +++ b/data/import-verification/02-standard-formats/results/standard-rules-xlsx.yaml @@ -0,0 +1,71 @@ +# [DUPLICATE: exact] 重复自定义规则 no-hardcoded-secret(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-hardcoded-credentials +# severity: error +# description: 禁止在源码中硬编码密码、令牌、API Key 等敏感凭证 +# message: 检测到疑似硬编码凭证,请使用环境变量或密钥管理服务注入 +# languages: [javascript, typescript, java] +# duplicateOf: custom/no-hardcoded-secret +# duplicateLevel: exact +# [DUPLICATE: exact] 重复 eslint/no-eval(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-eval-usage +# severity: error +# description: 禁止使用 eval() 函数,存在代码注入风险 +# message: eval() 存在安全风险,请使用 JSON.parse() 或 Function 构造器替代 +# languages: [javascript, typescript] +# duplicateOf: eslint/no-eval +# duplicateLevel: exact +- id: no-innerhtml-assignment + severity: warning + description: 禁止直接赋值 innerHTML,可能导致 XSS + message: 避免直接操作 innerHTML,请使用 textContent 或 DOMPurify 清洗 +- id: require-constant-case + severity: warning + description: 常量命名必须使用全大写加下划线(SCREAMING_SNAKE_CASE) + message: 常量应使用全大写命名,如 MAX_RETRY_COUNT + languages: [javascript, typescript, java] +- id: require-boolean-prefix + severity: info + description: 布尔变量和方法名应以 is/has/can/should 开头 + message: 布尔变量建议添加 is/has/can/should 前缀以提升可读性 + languages: [javascript, typescript] +- id: no-nested-loops-deep + severity: warning + description: 禁止三层及以上嵌套循环,时间复杂度过高 + message: 检测到深层嵌套循环(≥3层),建议重构为扁平结构或使用查找表优化 + languages: [javascript, typescript, java] +- id: no-sync-in-async + severity: warning + description: 异步函数内禁止调用同步阻塞 API + message: 在 async 函数中调用同步 API 会阻塞事件循环,请改用异步版本 + languages: [javascript, typescript] +- id: require-type-annotation + severity: info + description: 函数参数和返回值应显式标注 TypeScript 类型 + message: 建议为函数添加显式类型注解,提升类型安全性 + languages: [typescript] +# [DUPLICATE: exact] 重复自定义规则 no-magic-numbers(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-magic-numbers +# severity: info +# description: 禁止在代码中直接使用魔法数字,应提取为命名常量 +# message: 检测到魔法数字,建议提取为具名常量以提升可维护性 +# languages: [javascript, typescript] +# duplicateOf: custom/no-magic-numbers +# duplicateLevel: exact +- id: require-error-context + severity: warning + description: throw 语句必须携带错误上下文信息 + message: throw 时应提供足够的上下文信息,便于问题定位 + languages: [javascript, typescript, java] +- id: no-todo-in-production + severity: info + description: 生产代码中不应遗留 TODO/FIXME/HACK 注释 + message: 代码中发现 TODO/FIXME/HACK 注释,请在发布前处理 + excludeLanguages: [sql] +- id: require-function-doc + severity: info + description: 公共函数应添加文档注释(JSDoc / Javadoc) + message: 公共函数缺少文档注释,建议补充说明用途、参数和返回值 + languages: [javascript, typescript, java] \ No newline at end of file diff --git a/data/import-verification/02-standard-formats/results/standard-rules-yaml.yaml b/data/import-verification/02-standard-formats/results/standard-rules-yaml.yaml new file mode 100644 index 0000000..4752852 --- /dev/null +++ b/data/import-verification/02-standard-formats/results/standard-rules-yaml.yaml @@ -0,0 +1,96 @@ +# ┌─────────────────────────────────────────────────────┐ +# │ 净码特工 · Code Purifier — 用户自定义规则文件 │ +# │ 文件路径:.code-review/rules/user-rules.yaml │ +# │ 格式说明:YAML 数组,每条规则为一个 - id 开头的条目 │ +# └─────────────────────────────────────────────────────┘ +# +# 字段说明: +# id 必填,规则唯一标识(kebab-case) +# severity 必填,严重度:error / warning / info +# description 必填,规则简要描述 +# message 必填,展示给开发者的提示消息 +# languages 可选,规则生效的语言列表(不填则对所有语言生效) +# excludeLanguages 可选,规则排除的语言列表(优先级高于 languages) +# +# 内行数组语法:[javascript, typescript] + +# ── 安全类 ────────────────────────────────────────────── + +- id: no-hardcoded-credentials + severity: error + description: 禁止在源码中硬编码密码、令牌、API Key 等敏感凭证 + message: 检测到疑似硬编码凭证,请使用环境变量或密钥管理服务注入 + languages: [javascript, typescript, java] + +- id: no-eval-usage + severity: error + description: 禁止使用 eval() 函数,存在代码注入风险 + message: eval() 存在安全风险,请使用 JSON.parse() 或 Function 构造器替代 + languages: [javascript, typescript] + +- id: no-innerhtml-assignment + severity: warning + description: 禁止直接赋值 innerHTML,可能导致 XSS + message: 避免直接操作 innerHTML,请使用 textContent 或 DOMPurify 清洗 + +# ── 命名规范类 ────────────────────────────────────────── + +- id: require-constant-case + severity: warning + description: 常量命名必须使用全大写加下划线(SCREAMING_SNAKE_CASE) + message: 常量应使用全大写命名,如 MAX_RETRY_COUNT + languages: [javascript, typescript, java] + +- id: require-boolean-prefix + severity: info + description: 布尔变量和方法名应以 is/has/can/should 开头 + message: 布尔变量建议添加 is/has/can/should 前缀以提升可读性 + languages: [javascript, typescript] + +# ── 性能类 ────────────────────────────────────────────── + +- id: no-nested-loops-deep + severity: warning + description: 禁止三层及以上嵌套循环,时间复杂度过高 + message: 检测到深层嵌套循环(≥3层),建议重构为扁平结构或使用查找表优化 + languages: [javascript, typescript, java] + +- id: no-sync-in-async + severity: warning + description: 异步函数内禁止调用同步阻塞 API + message: 在 async 函数中调用同步 API 会阻塞事件循环,请改用异步版本 + languages: [javascript, typescript] + +# ── 代码风格类 ────────────────────────────────────────── + +- id: require-type-annotation + severity: info + description: 函数参数和返回值应显式标注 TypeScript 类型 + message: 建议为函数添加显式类型注解,提升类型安全性 + languages: [typescript] + +- id: no-magic-numbers + severity: info + description: 禁止在代码中直接使用魔法数字,应提取为命名常量 + message: 检测到魔法数字,建议提取为具名常量以提升可维护性 + languages: [javascript, typescript] + +# ── 团队约定类 ────────────────────────────────────────── + +- id: require-error-context + severity: warning + description: throw 语句必须携带错误上下文信息 + message: throw 时应提供足够的上下文信息,便于问题定位 + languages: [javascript, typescript, java] + +- id: no-todo-in-production + severity: info + description: 生产代码中不应遗留 TODO/FIXME/HACK 注释 + message: 代码中发现 TODO/FIXME/HACK 注释,请在发布前处理 + excludeLanguages: [sql] + +- id: require-function-doc + severity: info + description: 公共函数应添加文档注释(JSDoc / Javadoc) + message: 公共函数缺少文档注释,建议补充说明用途、参数和返回值 + languages: [javascript, typescript, java] diff --git a/data/import-verification/02-standard-formats/team-coding-rules-multi-sheet.xlsx b/data/import-verification/02-standard-formats/team-coding-rules-multi-sheet.xlsx new file mode 100644 index 0000000..cd960ce Binary files /dev/null and b/data/import-verification/02-standard-formats/team-coding-rules-multi-sheet.xlsx differ diff --git a/data/import-verification/02-standard-formats/team-coding-rules-template.xlsx b/data/import-verification/02-standard-formats/team-coding-rules-template.xlsx new file mode 100644 index 0000000..f580150 Binary files /dev/null and b/data/import-verification/02-standard-formats/team-coding-rules-template.xlsx differ diff --git a/data/import-verification/02-standard-formats/team-coding-rules.docx b/data/import-verification/02-standard-formats/team-coding-rules.docx new file mode 100644 index 0000000..cfdec08 Binary files /dev/null and b/data/import-verification/02-standard-formats/team-coding-rules.docx differ diff --git a/data/import-verification/02-standard-formats/team-coding-rules.md b/data/import-verification/02-standard-formats/team-coding-rules.md new file mode 100644 index 0000000..d70a734 --- /dev/null +++ b/data/import-verification/02-standard-formats/team-coding-rules.md @@ -0,0 +1,96 @@ +# 团队代码审查规范 + +> 本文档定义了团队代码审查中需要遵循的自定义规则,涵盖安全、命名、性能、代码风格和团队约定五个维度。 + +## 一、安全类规则 + +### 1.1 禁止硬编码凭证 + +**严重级别**:error +**适用语言**:JavaScript、TypeScript、Java + +禁止在源码中硬编码密码、令牌、API Key 等敏感凭证。检测到疑似硬编码凭证时,请使用环境变量或密钥管理服务注入。 + +### 1.2 禁止使用 eval() + +**严重级别**:error +**适用语言**:JavaScript、TypeScript + +禁止使用 eval() 函数,存在代码注入风险。eval() 存在安全风险,请使用 JSON.parse() 或 Function 构造器替代。 + +### 1.3 禁止直接赋值 innerHTML + +**严重级别**:warning + +禁止直接赋值 innerHTML,可能导致 XSS。避免直接操作 innerHTML,请使用 textContent 或 DOMPurify 清洗。 + +## 二、命名规范类规则 + +### 2.1 常量使用全大写命名 + +**严重级别**:warning +**适用语言**:JavaScript、TypeScript、Java + +常量命名必须使用全大写加下划线(SCREAMING_SNAKE_CASE),如 MAX_RETRY_COUNT。 + +### 2.2 布尔变量添加前缀 + +**严重级别**:info +**适用语言**:JavaScript、TypeScript + +布尔变量和方法名应以 is/has/can/should 开头,以提升可读性。 + +## 三、性能类规则 + +### 3.1 禁止三层以上嵌套循环 + +**严重级别**:warning +**适用语言**:JavaScript、TypeScript、Java + +禁止三层及以上嵌套循环,时间复杂度过高。检测到深层嵌套循环(≥3层)时,建议重构为扁平结构或使用查找表优化。 + +### 3.2 异步函数内禁止同步 API + +**严重级别**:warning +**适用语言**:JavaScript、TypeScript + +异步函数内禁止调用同步阻塞 API。在 async 函数中调用同步 API 会阻塞事件循环,请改用异步版本。 + +## 四、代码风格类规则 + +### 4.1 函数显式类型注解 + +**严重级别**:info +**适用语言**:TypeScript + +函数参数和返回值应显式标注 TypeScript 类型,提升类型安全性。 + +### 4.2 禁止魔法数字 + +**严重级别**:info +**适用语言**:JavaScript、TypeScript + +禁止在代码中直接使用魔法数字,应提取为命名常量以提升可维护性。 + +## 五、团队约定类规则 + +### 5.1 throw 语句携带上下文 + +**严重级别**:warning +**适用语言**:JavaScript、TypeScript、Java + +throw 语句必须携带错误上下文信息,便于问题定位。 + +### 5.2 禁止遗留 TODO 注释 + +**严重级别**:info +**排除语言**:SQL + +生产代码中不应遗留 TODO/FIXME/HACK 注释,请在发布前处理。 + +### 5.3 公共函数文档注释 + +**严重级别**:info +**适用语言**:JavaScript、TypeScript、Java + +公共函数应添加文档注释(JSDoc / Javadoc),说明用途、参数和返回值。 diff --git a/data/import-verification/02-standard-formats/team-coding-rules.pptx b/data/import-verification/02-standard-formats/team-coding-rules.pptx new file mode 100644 index 0000000..38887a8 Binary files /dev/null and b/data/import-verification/02-standard-formats/team-coding-rules.pptx differ diff --git a/data/import-verification/02-standard-formats/team-coding-rules.txt b/data/import-verification/02-standard-formats/team-coding-rules.txt new file mode 100644 index 0000000..fdea5c2 --- /dev/null +++ b/data/import-verification/02-standard-formats/team-coding-rules.txt @@ -0,0 +1,73 @@ +团队代码审查规范 + +本文件定义了团队代码审查中需要遵循的自定义规则。 + +=== 安全类 === + +1. 禁止在源码中硬编码密码、令牌、API Key 等敏感凭证 + 严重级别:error + 适用语言:javascript, typescript, java + 提示:检测到疑似硬编码凭证,请使用环境变量或密钥管理服务注入 + +2. 禁止使用 eval() 函数,存在代码注入风险 + 严重级别:error + 适用语言:javascript, typescript + 提示:eval() 存在安全风险,请使用 JSON.parse() 或 Function 构造器替代 + +3. 禁止直接赋值 innerHTML,可能导致 XSS + 严重级别:warning + 适用语言:所有语言 + 提示:避免直接操作 innerHTML,请使用 textContent 或 DOMPurify 清洗 + +=== 命名规范类 === + +4. 常量命名必须使用全大写加下划线(SCREAMING_SNAKE_CASE) + 严重级别:warning + 适用语言:javascript, typescript, java + 提示:常量应使用全大写命名,如 MAX_RETRY_COUNT + +5. 布尔变量和方法名应以 is/has/can/should 开头 + 严重级别:info + 适用语言:javascript, typescript + 提示:布尔变量建议添加 is/has/can/should 前缀以提升可读性 + +=== 性能类 === + +6. 禁止三层及以上嵌套循环,时间复杂度过高 + 严重级别:warning + 适用语言:javascript, typescript, java + 提示:检测到深层嵌套循环(≥3层),建议重构为扁平结构或使用查找表优化 + +7. 异步函数内禁止调用同步阻塞 API + 严重级别:warning + 适用语言:javascript, typescript + 提示:在 async 函数中调用同步 API 会阻塞事件循环,请改用异步版本 + +=== 代码风格类 === + +8. 函数参数和返回值应显式标注 TypeScript 类型 + 严重级别:info + 适用语言:typescript + 提示:建议为函数添加显式类型注解,提升类型安全性 + +9. 禁止在代码中直接使用魔法数字,应提取为命名常量 + 严重级别:info + 适用语言:javascript, typescript + 提示:检测到魔法数字,建议提取为具名常量以提升可维护性 + +=== 团队约定类 === + +10. throw 语句必须携带错误上下文信息 + 严重级别:warning + 适用语言:javascript, typescript, java + 提示:throw 时应提供足够的上下文信息,便于问题定位 + +11. 生产代码中不应遗留 TODO/FIXME/HACK 注释 + 严重级别:info + 排除语言:sql + 提示:代码中发现 TODO/FIXME/HACK 注释,请在发布前处理 + +12. 公共函数应添加文档注释(JSDoc / Javadoc) + 严重级别:info + 适用语言:javascript, typescript, java + 提示:公共函数缺少文档注释,建议补充说明用途、参数和返回值 diff --git a/data/import-verification/02-standard-formats/team-coding-rules.xlsx b/data/import-verification/02-standard-formats/team-coding-rules.xlsx new file mode 100644 index 0000000..a23405b Binary files /dev/null and b/data/import-verification/02-standard-formats/team-coding-rules.xlsx differ diff --git a/data/import-verification/02-standard-formats/team-coding-rules.yaml b/data/import-verification/02-standard-formats/team-coding-rules.yaml new file mode 100644 index 0000000..4752852 --- /dev/null +++ b/data/import-verification/02-standard-formats/team-coding-rules.yaml @@ -0,0 +1,96 @@ +# ┌─────────────────────────────────────────────────────┐ +# │ 净码特工 · Code Purifier — 用户自定义规则文件 │ +# │ 文件路径:.code-review/rules/user-rules.yaml │ +# │ 格式说明:YAML 数组,每条规则为一个 - id 开头的条目 │ +# └─────────────────────────────────────────────────────┘ +# +# 字段说明: +# id 必填,规则唯一标识(kebab-case) +# severity 必填,严重度:error / warning / info +# description 必填,规则简要描述 +# message 必填,展示给开发者的提示消息 +# languages 可选,规则生效的语言列表(不填则对所有语言生效) +# excludeLanguages 可选,规则排除的语言列表(优先级高于 languages) +# +# 内行数组语法:[javascript, typescript] + +# ── 安全类 ────────────────────────────────────────────── + +- id: no-hardcoded-credentials + severity: error + description: 禁止在源码中硬编码密码、令牌、API Key 等敏感凭证 + message: 检测到疑似硬编码凭证,请使用环境变量或密钥管理服务注入 + languages: [javascript, typescript, java] + +- id: no-eval-usage + severity: error + description: 禁止使用 eval() 函数,存在代码注入风险 + message: eval() 存在安全风险,请使用 JSON.parse() 或 Function 构造器替代 + languages: [javascript, typescript] + +- id: no-innerhtml-assignment + severity: warning + description: 禁止直接赋值 innerHTML,可能导致 XSS + message: 避免直接操作 innerHTML,请使用 textContent 或 DOMPurify 清洗 + +# ── 命名规范类 ────────────────────────────────────────── + +- id: require-constant-case + severity: warning + description: 常量命名必须使用全大写加下划线(SCREAMING_SNAKE_CASE) + message: 常量应使用全大写命名,如 MAX_RETRY_COUNT + languages: [javascript, typescript, java] + +- id: require-boolean-prefix + severity: info + description: 布尔变量和方法名应以 is/has/can/should 开头 + message: 布尔变量建议添加 is/has/can/should 前缀以提升可读性 + languages: [javascript, typescript] + +# ── 性能类 ────────────────────────────────────────────── + +- id: no-nested-loops-deep + severity: warning + description: 禁止三层及以上嵌套循环,时间复杂度过高 + message: 检测到深层嵌套循环(≥3层),建议重构为扁平结构或使用查找表优化 + languages: [javascript, typescript, java] + +- id: no-sync-in-async + severity: warning + description: 异步函数内禁止调用同步阻塞 API + message: 在 async 函数中调用同步 API 会阻塞事件循环,请改用异步版本 + languages: [javascript, typescript] + +# ── 代码风格类 ────────────────────────────────────────── + +- id: require-type-annotation + severity: info + description: 函数参数和返回值应显式标注 TypeScript 类型 + message: 建议为函数添加显式类型注解,提升类型安全性 + languages: [typescript] + +- id: no-magic-numbers + severity: info + description: 禁止在代码中直接使用魔法数字,应提取为命名常量 + message: 检测到魔法数字,建议提取为具名常量以提升可维护性 + languages: [javascript, typescript] + +# ── 团队约定类 ────────────────────────────────────────── + +- id: require-error-context + severity: warning + description: throw 语句必须携带错误上下文信息 + message: throw 时应提供足够的上下文信息,便于问题定位 + languages: [javascript, typescript, java] + +- id: no-todo-in-production + severity: info + description: 生产代码中不应遗留 TODO/FIXME/HACK 注释 + message: 代码中发现 TODO/FIXME/HACK 注释,请在发布前处理 + excludeLanguages: [sql] + +- id: require-function-doc + severity: info + description: 公共函数应添加文档注释(JSDoc / Javadoc) + message: 公共函数缺少文档注释,建议补充说明用途、参数和返回值 + languages: [javascript, typescript, java] diff --git a/data/import-verification/03-irregular-content/result-report.md b/data/import-verification/03-irregular-content/result-report.md new file mode 100644 index 0000000..81dfbec --- /dev/null +++ b/data/import-verification/03-irregular-content/result-report.md @@ -0,0 +1,94 @@ +# 不规则内容导入 — 手动验证结果报告(7 种格式全量) + +## 验证信息 + +| 项 | 值 | +|---|---| +| 验证日期 | 2026-09-07 | +| 验证功能 | 自定义规则导入——不规则规则内容(重噪声嵌入)的 7 种文件格式逐一导入 | +| 导入素材 | `data/import-verification/03-irregular-content/team-coding-rules.*`(7 个文件) | +| 导入结果 | `data/import-verification/03-irregular-content/results/irregular-*.yaml`(7 个文件,已全部移出激活目录归档) | +| 规则基准 | 与场景②相同的 12 条规则(id 亦相同),severity 基准 error×2 / warning×5 / info×5 | +| 噪声设计 | 项目背景、团队介绍(12 人分工)、会议纪要、部署流程、版本历史、反面/正面代码示例(硬编码密码 `Admin@123456`、eval 调用、三层循环等)、内部 wiki 链接、Checklist | +| 验证方式 | 在 Extension Development Host 中手动执行完整导入流程(含预览确认),每轮结果落盘核对后归档 | + +## 素材矩阵 + +| # | 文件 | 格式 | 导入路径 | AI 内容转换 | +|---|---|---|---|---| +| 1 | team-coding-rules.yaml | YAML(噪声全在注释) | YamlConverter 直读 | 否 | +| 2 | team-coding-rules.md | Markdown(噪声为真实正文) | 读文本 → AI(freeform) | 是 | +| 3 | team-coding-rules.txt | 纯文本 | 读文本 → AI(freeform) | 是 | +| 4 | team-coding-rules.docx | Word | mammoth 提取 → AI(freeform) | 是 | +| 5 | team-coding-rules.pptx | PowerPoint | officeparser 提取 → AI(freeform) | 是 | +| 6 | team-coding-rules.xlsx | Excel 单表 | 表格 → Markdown → AI(spreadsheet) | 是 | +| 7 | team-coding-rules-multi-sheet.xlsx | Excel 多表 | 逐表渲染合并 → AI(spreadsheet) | 是 | + +(无 template 轮:模板路径为严格表头校验直读,不适配不规则内容场景。) + +## 逐轮结果总表 + +| 轮 | 格式(规则名) | 检出条数 | severity | languages | id 与基准 | 去重标注 | 结论 | +|---|---|---|---|---|---|---|---| +| 1 | yaml(irregular-yaml) | 12/12 | ✅ 全对 | ✅ 全对 | 逐字节一致 | 预览阶段独立去重 | 通过 | +| 2 | md | 12/12 | ✅ 全对 | ✅ 全对 | 漂移(语义等价) | 3 exact,指向真实 | 通过 | +| 3 | txt | 12/12 | ✅ 全对 | ✅ 全对 | 漂移 | 3 exact,同构 | 通过 | +| 4 | docx | 12/12 | ✅ 全对 | ✅ 全对 | 漂移 | 3 exact,同构 | 通过 | +| 5 | pptx | 12/12 | ✅ 全对 | ✅ **全对(零丢失)** | 漂移 | 3 exact,同构 | 通过 | +| 6 | xlsx 单表 | 12/12 | ✅ 全对 | ✅ 全对 | **完全一致** | **2 exact + 1 overlap**(见发现 3) | 通过 | +| 7 | xlsx 多表 | 12/12 | ✅ 全对 | ✅ 全对 | **完全一致** | 3 exact,回归同构 | 通过 | + +## 关键发现 + +### 1. 噪声过滤全场景零失守(本场景核心目标达成) + +7 轮全部通过以下陷阱测试: + +- 项目背景、团队介绍(12 人分工)、会议纪要(「决定在 async 函数中全面禁用同步 API」)、部署流程、版本历史(张三/李四/王五)、Checklist、内部 wiki 链接——**均未变成规则** +- **反面示例陷阱零触发**:代码示例中的 `"Admin@123456"`、`eval(request.body)`、`maxRetry = 3` 等错误示范未被生成为规则,也未污染规则语义 +- **叙事与规则分离**:如「上周代码审查中发现前端模块有 eval() 调用」的叙事上下文被剥离,只提取规则本身 + +### 2. pptx 语言字段差异根因定案:源文件内容差异,AI 两轮行为均正确 + +| 证据 | languages 表现 | +|---|---| +| 场景② pptx | 留空 6 处(当时误判「降级/丢失」) | +| 旧散落结果 rules_ppt.yaml | 大面积留空 | +| 本场景 pptx(噪声更重、文件更大 45KB) | 零留空,8 处全对 | +| 场景② pptx 重测(2026-09-07) | 留空模式与首测逐字段复现 | +| **officeparser 提取文本比对(2026-09-07)** | **02 源文件 950 字符中无任何「适用语言/排除语言」标注;03 源文件含成组「严重级别 \| 语言」标注及「排除语言:sql」** | + +定性演进三版:格式缺陷(02 初稿)→ 高方差(03 初稿,被重测推翻)→ 提取层丢失(被提取比对推翻)→ **最终定案:源文件内容差异**。02 pptx 幻灯片只写了 severity(`[error]/[warning]/[info]` 前缀)没写语言,03 pptx 两者都写了。AI 侧两轮行为均正确:源有的正确映射(含 excludeLanguages: [sql]),源无的按「严禁猜测,留空比猜测错误更安全」留空,语义可推的唯一一条(描述含「TypeScript 类型」)正确推断 [typescript]。**这 6 处留空从来不是「丢失」——源文件没有的数据不能叫丢失**。制作 pptx 规则素材时,如需语言限定必须在幻灯片中显式标注适用语言。 + +### 3. 去重判断方差实锤:同一规则跨轮在 exact 与 overlap 间摆动 + +- xlsx 单表轮:no-hardcoded-credentials 被判 **overlap**(保留生效)——与前 12 轮历史(exact)不同,且两条规则检测目标几乎重合、语言集合相同,exact 更贴切 +- multisheet 轮:**回归 exact**(注释) +- 实际影响:overlap 判保留时该规则与 custom/no-hardcoded-secret 并存双报。定性为 AI 判断方差(与 galaxy 轮次波动同源),预览面板人工复核是设计内的必要补偿 +- 附加证据:docx 轮魔法数字规则 id 为 `avoid-magic-numbers`(与既有规则 id 前缀完全不同),仍被精准标注为 custom/no-magic-numbers 的 exact——去重的语义性(与 id 无关)得到最直接验证 + +### 4. 表格类格式稳定性跨场景复现,multisheet 打出跨场景字节级一致 + +- xlsx 单表、multisheet 两轮的 9 条保留规则 id 再次全部与 yaml 基准一致(「结构化表格 → id 收敛」跨场景复现;自由文本四轮 id 依旧逐轮漂移) +- **multisheet 轮落盘文件与场景② multisheet 结果逐字节一致**(fc 0 差异),且场景②内 multisheet ≡ xlsx 单表——推导链 `02-xlsx ≡ 02-multisheet ≡ 03-multisheet`:AI 从两份完全不同的源文档(15KB 标准多表 vs 24KB 重噪声多表)收敛到同一字节级输出,spreadsheet 链路稳定性拿到最强证据 + +### 5. id 漂移全景 + +自由文本格式(md/txt/docx/pptx)的 AI 生成 id 逐轮漂移(本轮新组合:`constant-naming`、`boolean-variable-prefix`、`require-explicit-types`、`no-todo-fixme-hack` 等),仅个别巧合重合(no-todo-comments、require-doc-comments 在 02/03 的 md 轮均出现)。含义相同的规则若以不同格式多次导入并存将双报——每轮归档移出激活目录即为规避此问题。 + +## 已知观察 + +- **xlsx 轮注释块尾部各多一行孤立 `#`**(外观残留,无功能影响) +- **去重方差的管理含义**:exact/overlap 判定在边界案例上有摆动,重要场景导入后应在预览面板复核重复分组(与 guide.md 归档流程互补) +- 本场景 yaml 轮噪声全部藏在注释中,对解析器无挑战(真正考验由 md/txt/docx/pptx/xlsx 承担) + +## 结论 + +**通过**。7 种格式全部成功导入 12 条规则基准:重噪声零膨胀、反面示例陷阱零触发、severity 零偏差。场景②的 pptx 疑问在本场景得到最终定案:语言字段差异源于源文件内容差异(02 源无语言标注、03 源有),AI 两轮行为均正确,不存在降级或丢失;表格类格式稳定性获得跨场景字节级一致的强证据。去重语义性(avoid-magic-numbers 案例)与判断方差(hardcoded-credentials exact/overlap 摆动)均有实测记录。 + +## 关联 + +- galaxy 素材验证报告:`data/import-verification/01-galaxy-nonstandard/result-report.md`(真实世界非标准格式场景) +- 标准格式验证报告:`data/import-verification/02-standard-formats/result-report.md`(8 种格式,含 pptx 降级原始记录) +- 自动化测试:`tests/excel-converter.test.ts`(转换器渲染层) +- 设计 spec:`docs/superpowers/specs/2026-07-26-custom-rule-import-ux-design.md` diff --git a/data/import-verification/03-irregular-content/results/irregular-docx.yaml b/data/import-verification/03-irregular-content/results/irregular-docx.yaml new file mode 100644 index 0000000..56d905b --- /dev/null +++ b/data/import-verification/03-irregular-content/results/irregular-docx.yaml @@ -0,0 +1,71 @@ +# [DUPLICATE: exact] 重复自定义规则 no-hardcoded-secret(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-hardcoded-credentials +# severity: error +# description: 禁止在源码中硬编码密码、令牌、API Key 等敏感凭证 +# message: 检测到疑似硬编码凭证,请使用环境变量或密钥管理服务注入 +# languages: [javascript, typescript, java] +# duplicateOf: custom/no-hardcoded-secret +# duplicateLevel: exact +# [DUPLICATE: exact] 重复 eslint/no-eval(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-eval +# severity: error +# description: 禁止使用 eval() 函数,存在代码注入风险 +# message: eval() 存在安全风险,请使用 JSON.parse() 或 Function 构造器替代 +# languages: [javascript, typescript] +# duplicateOf: eslint/no-eval +# duplicateLevel: exact +- id: no-innerhtml-assignment + severity: warning + description: 禁止直接赋值 innerHTML,可能导致 XSS + message: 避免直接操作 innerHTML,请使用 textContent 或 DOMPurify 清洗 +- id: constants-screaming-snake-case + severity: warning + description: 常量命名必须使用全大写加下划线(SCREAMING_SNAKE_CASE) + message: 常量应使用全大写命名,如 MAX_RETRY_COUNT + languages: [javascript, typescript, java] +- id: boolean-prefix-naming + severity: info + description: 布尔变量和方法名应以 is/has/can/should 开头 + message: 布尔变量建议添加 is/has/can/should 前缀以提升可读性 + languages: [javascript, typescript] +- id: no-deep-nested-loops + severity: warning + description: 禁止三层及以上嵌套循环,时间复杂度过高 + message: 检测到深层嵌套循环(≥3层),建议重构为扁平结构或使用查找表优化 + languages: [javascript, typescript, java] +- id: no-sync-api-in-async + severity: warning + description: 异步函数内禁止调用同步阻塞 API + message: 在 async 函数中调用同步 API 会阻塞事件循环,请改用异步版本 + languages: [javascript, typescript] +- id: explicit-function-types + severity: info + description: 函数参数和返回值应显式标注 TypeScript 类型 + message: 建议为函数添加显式类型注解,提升类型安全性 + languages: [typescript] +# [DUPLICATE: exact] 重复自定义规则 no-magic-numbers(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: avoid-magic-numbers +# severity: info +# description: 禁止在代码中直接使用魔法数字,应提取为命名常量 +# message: 检测到魔法数字,建议提取为具名常量以提升可维护性 +# languages: [javascript, typescript] +# duplicateOf: custom/no-magic-numbers +# duplicateLevel: exact +- id: throw-with-context + severity: warning + description: throw 语句必须携带错误上下文信息 + message: throw 时应提供足够的上下文信息,便于问题定位 + languages: [javascript, typescript, java] +- id: no-todo-fixme-hack + severity: info + description: 生产代码中不应遗留 TODO/FIXME/HACK 注释 + message: 代码中发现 TODO/FIXME/HACK 注释,请在发布前处理 + excludeLanguages: [sql] +- id: require-public-docs + severity: info + description: 公共函数应添加文档注释(JSDoc / Javadoc) + message: 公共函数缺少文档注释,建议补充说明用途、参数和返回值 + languages: [javascript, typescript, java] \ No newline at end of file diff --git a/data/import-verification/03-irregular-content/results/irregular-md.yaml b/data/import-verification/03-irregular-content/results/irregular-md.yaml new file mode 100644 index 0000000..11ed44d --- /dev/null +++ b/data/import-verification/03-irregular-content/results/irregular-md.yaml @@ -0,0 +1,71 @@ +# [DUPLICATE: exact] 重复自定义规则 no-hardcoded-secret(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-hardcoded-credentials +# severity: error +# description: 禁止在源码中硬编码密码、令牌、API Key 等敏感凭证 +# message: 检测到疑似硬编码凭证,请使用环境变量或密钥管理服务注入 +# languages: [java, javascript, typescript] +# duplicateOf: custom/no-hardcoded-secret +# duplicateLevel: exact +# [DUPLICATE: exact] 重复 eslint/no-eval(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-eval +# severity: error +# description: 禁止使用 eval() +# message: eval() 存在代码注入风险,请使用 JSON.parse() 或 Function 构造器替代 +# languages: [javascript, typescript] +# duplicateOf: eslint/no-eval +# duplicateLevel: exact +- id: no-innerhtml-assignment + severity: warning + description: 禁止直接赋值 innerHTML + message: 避免直接操作 innerHTML,请使用 textContent 或 DOMPurify 清洗 +- id: constant-naming + severity: warning + description: 常量命名必须使用全大写加下划线的 SCREAMING_SNAKE_CASE + message: 常量应使用全大写命名,如 MAX_RETRY_COUNT + languages: [java, javascript, typescript] +- id: boolean-prefix + severity: info + description: 布尔变量和方法名应以 is/has/can/should 开头 + message: 布尔变量和方法名建议添加 is/has/can/should 前缀以提升可读性 + languages: [javascript, typescript] +- id: no-deep-nested-loops + severity: warning + description: 禁止三层及以上嵌套循环 + message: 检测到深层嵌套循环,建议重构为扁平结构或使用查找表优化 + languages: [java, javascript, typescript] +- id: no-sync-api-in-async + severity: warning + description: 异步函数内禁止调用同步阻塞 API + message: 在 async 函数中调用同步 API 会阻塞事件循环,请改用异步版本 + languages: [javascript, typescript] +- id: require-explicit-types + severity: info + description: 函数参数和返回值应显式标注 TypeScript 类型 + message: 建议为函数添加显式类型注解,提升类型安全性 + languages: [typescript] +# [DUPLICATE: exact] 重复自定义规则 no-magic-numbers(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-magic-numbers +# severity: info +# description: 禁止在代码中直接使用魔法数字,应提取为命名常量 +# message: 检测到魔法数字,建议提取为具名常量以提升可维护性 +# languages: [javascript, typescript] +# duplicateOf: custom/no-magic-numbers +# duplicateLevel: exact +- id: require-throw-context + severity: warning + description: throw 语句必须携带错误上下文信息 + message: throw 时应提供足够的上下文信息,便于问题定位 + languages: [java, javascript, typescript] +- id: no-todo-comments + severity: info + description: 生产代码中不应遗留 TODO/FIXME/HACK 注释 + message: 代码中发现 TODO/FIXME/HACK 注释,请在发布前处理 + excludeLanguages: [sql] +- id: require-doc-comments + severity: info + description: 公共函数应添加文档注释(JSDoc / Javadoc) + message: 公共函数缺少文档注释,建议补充说明用途、参数和返回值 + languages: [java, javascript, typescript] \ No newline at end of file diff --git a/data/import-verification/03-irregular-content/results/irregular-multisheet.yaml b/data/import-verification/03-irregular-content/results/irregular-multisheet.yaml new file mode 100644 index 0000000..6f83f53 --- /dev/null +++ b/data/import-verification/03-irregular-content/results/irregular-multisheet.yaml @@ -0,0 +1,71 @@ +# [DUPLICATE: exact] 重复自定义规则 no-hardcoded-secret(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-hardcoded-credentials +# severity: error +# description: 禁止在源码中硬编码密码、令牌、API Key 等敏感凭证 +# message: 检测到疑似硬编码凭证,请使用环境变量或密钥管理服务注入 +# languages: [javascript, typescript, java] +# duplicateOf: custom/no-hardcoded-secret +# duplicateLevel: exact +# [DUPLICATE: exact] 重复 eslint/no-eval(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-eval-usage +# severity: error +# description: 禁止使用 eval() 函数,存在代码注入风险 +# message: eval() 存在安全风险,请使用 JSON.parse() 或 Function 构造器替代 +# languages: [javascript, typescript] +# duplicateOf: eslint/no-eval +# duplicateLevel: exact +- id: no-innerhtml-assignment + severity: warning + description: 禁止直接赋值 innerHTML,可能导致 XSS + message: 避免直接操作 innerHTML,请使用 textContent 或 DOMPurify 清洗 +- id: require-constant-case + severity: warning + description: 常量命名必须使用全大写加下划线(SCREAMING_SNAKE_CASE) + message: 常量应使用全大写命名,如 MAX_RETRY_COUNT + languages: [javascript, typescript, java] +- id: require-boolean-prefix + severity: info + description: 布尔变量和方法名应以 is/has/can/should 开头 + message: 布尔变量建议添加 is/has/can/should 前缀以提升可读性 + languages: [javascript, typescript] +- id: no-nested-loops-deep + severity: warning + description: 禁止三层及以上嵌套循环,时间复杂度过高 + message: 检测到深层嵌套循环(≥3层),建议重构为扁平结构或使用查找表优化 + languages: [javascript, typescript, java] +- id: no-sync-in-async + severity: warning + description: 异步函数内禁止调用同步阻塞 API + message: 在 async 函数中调用同步 API 会阻塞事件循环,请改用异步版本 + languages: [javascript, typescript] +- id: require-type-annotation + severity: info + description: 函数参数和返回值应显式标注 TypeScript 类型 + message: 建议为函数添加显式类型注解,提升类型安全性 + languages: [typescript] +# [DUPLICATE: exact] 重复自定义规则 no-magic-numbers(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-magic-numbers +# severity: info +# description: 禁止在代码中直接使用魔法数字,应提取为命名常量 +# message: 检测到魔法数字,建议提取为具名常量以提升可维护性 +# languages: [javascript, typescript] +# duplicateOf: custom/no-magic-numbers +# duplicateLevel: exact +- id: require-error-context + severity: warning + description: throw 语句必须携带错误上下文信息 + message: throw 时应提供足够的上下文信息,便于问题定位 + languages: [javascript, typescript, java] +- id: no-todo-in-production + severity: info + description: 生产代码中不应遗留 TODO/FIXME/HACK 注释 + message: 代码中发现 TODO/FIXME/HACK 注释,请在发布前处理 + excludeLanguages: [sql] +- id: require-function-doc + severity: info + description: 公共函数应添加文档注释(JSDoc / Javadoc) + message: 公共函数缺少文档注释,建议补充说明用途、参数和返回值 + languages: [javascript, typescript, java] \ No newline at end of file diff --git a/data/import-verification/03-irregular-content/results/irregular-pptx.yaml b/data/import-verification/03-irregular-content/results/irregular-pptx.yaml new file mode 100644 index 0000000..6659e7b --- /dev/null +++ b/data/import-verification/03-irregular-content/results/irregular-pptx.yaml @@ -0,0 +1,71 @@ +# [DUPLICATE: exact] 重复自定义规则 no-hardcoded-secret(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-hardcoded-secret +# severity: error +# description: 禁止在源码中硬编码密码、令牌、API Key 等敏感凭证 +# message: 检测到疑似硬编码凭证,请使用环境变量或密钥管理服务注入 +# languages: [javascript, typescript, java] +# duplicateOf: custom/no-hardcoded-secret +# duplicateLevel: exact +# [DUPLICATE: exact] 重复 eslint/no-eval(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-eval +# severity: error +# description: 禁止使用 eval() 函数 +# message: eval() 存在安全风险,请使用 JSON.parse() 或 Function 构造器替代 +# languages: [javascript, typescript] +# duplicateOf: eslint/no-eval +# duplicateLevel: exact +- id: no-inner-html + severity: warning + description: 禁止直接赋值 innerHTML + message: 避免直接操作 innerHTML,请使用 textContent 或 DOMPurify 清洗 +- id: constant-naming-screaming-snake-case + severity: warning + description: 常量命名必须使用全大写加下划线(SCREAMING_SNAKE_CASE) + message: 常量应使用全大写命名,如 MAX_RETRY_COUNT + languages: [javascript, typescript, java] +- id: boolean-prefix + severity: info + description: 布尔变量和方法名应以 is/has/can/should 开头 + message: 布尔变量建议添加 is/has/can/should 前缀以提升可读性 + languages: [javascript, typescript] +- id: no-deep-nested-loops + severity: warning + description: 禁止三层及以上嵌套循环 + message: 检测到深层嵌套循环(≥3层),建议重构为扁平结构或使用查找表优化 + languages: [javascript, typescript, java] +- id: no-sync-in-async + severity: warning + description: 异步函数内禁止调用同步阻塞 API + message: 在 async 函数中调用同步 API 会阻塞事件循环,请改用异步版本 + languages: [javascript, typescript] +- id: require-explicit-types + severity: info + description: 函数参数和返回值应显式标注 TypeScript 类型 + message: 建议为函数添加显式类型注解,提升类型安全性 + languages: [typescript] +# [DUPLICATE: exact] 重复自定义规则 no-magic-numbers(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-magic-numbers +# severity: info +# description: 禁止在代码中直接使用魔法数字,应提取为命名常量 +# message: 检测到魔法数字,建议提取为具名常量以提升可维护性 +# languages: [javascript, typescript] +# duplicateOf: custom/no-magic-numbers +# duplicateLevel: exact +- id: throw-with-context + severity: warning + description: throw 语句必须携带错误上下文信息 + message: throw 时应提供足够的上下文信息,便于问题定位 + languages: [javascript, typescript, java] +- id: no-todo-fixme-hack + severity: info + description: 生产代码中不应遗留 TODO/FIXME/HACK 注释 + message: 代码中发现 TODO/FIXME/HACK 注释,请在发布前处理 + excludeLanguages: [sql] +- id: require-doc-comments + severity: info + description: 公共函数应添加文档注释(JSDoc / Javadoc) + message: 公共函数缺少文档注释,建议补充说明用途、参数和返回值 + languages: [javascript, typescript, java] \ No newline at end of file diff --git a/data/import-verification/03-irregular-content/results/irregular-txt.yaml b/data/import-verification/03-irregular-content/results/irregular-txt.yaml new file mode 100644 index 0000000..7ae8eea --- /dev/null +++ b/data/import-verification/03-irregular-content/results/irregular-txt.yaml @@ -0,0 +1,71 @@ +# [DUPLICATE: exact] 重复自定义规则 no-hardcoded-secret(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-hardcoded-credentials +# severity: error +# description: 禁止在源码中硬编码密码、令牌、API Key 等敏感凭证 +# message: 检测到疑似硬编码凭证,请使用环境变量或密钥管理服务注入 +# languages: [javascript, typescript, java] +# duplicateOf: custom/no-hardcoded-secret +# duplicateLevel: exact +# [DUPLICATE: exact] 重复 eslint/no-eval(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-eval +# severity: error +# description: 禁止使用 eval() 函数,存在代码注入风险 +# message: eval() 存在安全风险,请使用 JSON.parse() 或 Function 构造器替代 +# languages: [javascript, typescript] +# duplicateOf: eslint/no-eval +# duplicateLevel: exact +- id: no-innerhtml-assignment + severity: warning + description: 禁止直接赋值 innerHTML,可能导致 XSS + message: 避免直接操作 innerHTML,请使用 textContent 或 DOMPurify 清洗 +- id: constant-uppercase-naming + severity: warning + description: 常量命名必须使用全大写加下划线(SCREAMING_SNAKE_CASE) + message: 常量应使用全大写命名,如 MAX_RETRY_COUNT + languages: [javascript, typescript, java] +- id: boolean-variable-prefix + severity: info + description: 布尔变量和方法名应以 is/has/can/should 开头 + message: 布尔变量建议添加 is/has/can/should 前缀以提升可读性 + languages: [javascript, typescript] +- id: no-deeply-nested-loops + severity: warning + description: 禁止三层及以上嵌套循环,时间复杂度过高 + message: 检测到深层嵌套循环(≥3层),建议重构为扁平结构或使用查找表优化 + languages: [javascript, typescript, java] +- id: no-sync-api-in-async + severity: warning + description: 禁止在异步函数内调用同步阻塞 API + message: 在 async 函数中调用同步 API 会阻塞事件循环,请改用异步版本 + languages: [javascript, typescript] +- id: explicit-function-types + severity: info + description: 函数参数和返回值应显式标注 TypeScript 类型 + message: 建议为函数添加显式类型注解,提升类型安全性 + languages: [typescript] +# [DUPLICATE: exact] 重复自定义规则 no-magic-numbers(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-magic-numbers +# severity: info +# description: 禁止在代码中直接使用魔法数字,应提取为命名常量 +# message: 检测到魔法数字,建议提取为具名常量以提升可维护性 +# languages: [javascript, typescript] +# duplicateOf: custom/no-magic-numbers +# duplicateLevel: exact +- id: throw-with-context + severity: warning + description: throw 语句必须携带错误上下文信息 + message: throw 时应提供足够的上下文信息,便于问题定位 + languages: [javascript, typescript, java] +- id: no-todo-comments + severity: info + description: 生产代码中不应遗留 TODO/FIXME/HACK 注释 + message: 代码中发现 TODO/FIXME/HACK 注释,请在发布前处理 + excludeLanguages: [sql] +- id: public-function-doc-comments + severity: info + description: 公共函数应添加文档注释(JSDoc / Javadoc) + message: 公共函数缺少文档注释,建议补充说明用途、参数和返回值 + languages: [javascript, typescript, java] \ No newline at end of file diff --git a/data/import-verification/03-irregular-content/results/irregular-xlsx.yaml b/data/import-verification/03-irregular-content/results/irregular-xlsx.yaml new file mode 100644 index 0000000..2f04051 --- /dev/null +++ b/data/import-verification/03-irregular-content/results/irregular-xlsx.yaml @@ -0,0 +1,78 @@ +- id: no-hardcoded-credentials + severity: error + description: 禁止在源码中硬编码密码、令牌、API Key 等敏感凭证 + message: 检测到疑似硬编码凭证,请使用环境变量或密钥管理服务注入 + languages: [javascript, typescript, java] + +# [DUPLICATE: exact] 重复 eslint/no-eval(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-eval-usage +# severity: error +# description: 禁止使用 eval() 函数,存在代码注入风险 +# message: eval() 存在安全风险,请使用 JSON.parse() 或 Function 构造器替代 +# languages: [javascript, typescript] +# duplicateOf: eslint/no-eval +# duplicateLevel: exact +# +- id: no-innerhtml-assignment + severity: warning + description: 禁止直接赋值 innerHTML,可能导致 XSS + message: 避免直接操作 innerHTML,请使用 textContent 或 DOMPurify 清洗 + +- id: require-constant-case + severity: warning + description: 常量命名必须使用全大写加下划线(SCREAMING_SNAKE_CASE) + message: 常量应使用全大写命名,如 MAX_RETRY_COUNT + languages: [javascript, typescript, java] + +- id: require-boolean-prefix + severity: info + description: 布尔变量和方法名应以 is/has/can/should 开头 + message: 布尔变量建议添加 is/has/can/should 前缀以提升可读性 + languages: [javascript, typescript] + +- id: no-nested-loops-deep + severity: warning + description: 禁止三层及以上嵌套循环,时间复杂度过高 + message: 检测到深层嵌套循环(≥3层),建议重构为扁平结构或使用查找表优化 + languages: [javascript, typescript, java] + +- id: no-sync-in-async + severity: warning + description: 异步函数内禁止调用同步阻塞 API + message: 在 async 函数中调用同步 API 会阻塞事件循环,请改用异步版本 + languages: [javascript, typescript] + +- id: require-type-annotation + severity: info + description: 函数参数和返回值应显式标注 TypeScript 类型 + message: 建议为函数添加显式类型注解,提升类型安全性 + languages: [typescript] + +# [DUPLICATE: exact] 重复自定义规则 no-magic-numbers(检测目标完全一致) +# 如需启用,删除以下每行开头的 # 即可 +# - id: no-magic-numbers +# severity: info +# description: 禁止在代码中直接使用魔法数字,应提取为命名常量 +# message: 检测到魔法数字,建议提取为具名常量以提升可维护性 +# languages: [javascript, typescript] +# duplicateOf: custom/no-magic-numbers +# duplicateLevel: exact +# +- id: require-error-context + severity: warning + description: throw 语句必须携带错误上下文信息 + message: throw 时应提供足够的上下文信息,便于问题定位 + languages: [javascript, typescript, java] + +- id: no-todo-in-production + severity: info + description: 生产代码中不应遗留 TODO/FIXME/HACK 注释 + message: 代码中发现 TODO/FIXME/HACK 注释,请在发布前处理 + excludeLanguages: [sql] + +- id: require-function-doc + severity: info + description: 公共函数应添加文档注释(JSDoc / Javadoc) + message: 公共函数缺少文档注释,建议补充说明用途、参数和返回值 + languages: [javascript, typescript, java] \ No newline at end of file diff --git a/data/import-verification/03-irregular-content/results/irregular-yaml.yaml b/data/import-verification/03-irregular-content/results/irregular-yaml.yaml new file mode 100644 index 0000000..bbbe8ea --- /dev/null +++ b/data/import-verification/03-irregular-content/results/irregular-yaml.yaml @@ -0,0 +1,225 @@ +# ┌─────────────────────────────────────────────────────────────────┐ +# │ 电商订单管理系统 — 工程规范文档 │ +# │ 团队:订单研发团队(后端6人 + 前端3人 + QA2人 + DevOps1人) │ +# │ 最后更新:2026-07-15 │ +# │ 仓库:git@company.com:order-team/oms.git │ +# └─────────────────────────────────────────────────────────────────┘ +# +# 项目背景: +# 面向 B 端商家的电商订单管理系统,日均订单量约 50 万单。 +# 微服务架构:订单服务、支付服务、库存服务、物流服务。 +# 技术栈:Java 17 + Spring Boot 3.2 + React 18 + TypeScript 5.3 +# +# 架构说明: +# 订单服务采用 CQRS 模式,写操作走主库,读操作走从库。 +# 消息队列使用 RocketMQ 5.x。 +# +# 2026-07-15 会议纪要: +# - 讨论了 Node.js 事件循环阻塞问题 +# - 决定在 async 函数中全面禁用 fs.readFileSync 等同步 API +# - 下个 Sprint 开始 Code Review 时执行 +# +# 部署流程: +# 每周二、四发布,发布窗口 14:00-16:00。 +# CI/CD Pipeline 详见 Jenkins 配置。 +# +# 代码审查 Checklist: +# [ ] 安全规范是否遵守 +# [ ] 命名规范是否一致 +# [ ] 性能是否有明显瓶颈 +# [ ] 代码风格是否统一 +# [ ] 团队约定是否遵循 +# +# ── 安全类 ────────────────────────────────────────────────────────── +# +# 反面示例(请勿模仿): +# +# // Java: 硬编码密码 +# public class DatabaseConfig { +# private String password = "Admin@123456"; +# } +# +# // JavaScript: 使用 eval +# const data = eval(request.body); +# +# // JavaScript: innerHTML 赋值 +# element.innerHTML = userInput; +# +# 正确做法: +# +# @Value("${db.password}") +# private String password; +# +# const data = JSON.parse(request.body); +# +# element.textContent = userInput; +# + +- id: no-hardcoded-credentials + severity: error + description: 禁止在源码中硬编码密码、令牌、API Key 等敏感凭证 + message: 检测到疑似硬编码凭证,请使用环境变量或密钥管理服务注入 + languages: [javascript, typescript, java] + +- id: no-eval-usage + severity: error + description: 禁止使用 eval() 函数,存在代码注入风险 + message: eval() 存在安全风险,请使用 JSON.parse() 或 Function 构造器替代 + languages: [javascript, typescript] + +- id: no-innerhtml-assignment + severity: warning + description: 禁止直接赋值 innerHTML,可能导致 XSS + message: 避免直接操作 innerHTML,请使用 textContent 或 DOMPurify 清洗 + +# ── 命名规范类 ────────────────────────────────────────────────────── +# +# 参考规范: +# - Google Java Style Guide +# - Airbnb JavaScript Style Guide +# +# 反面示例: +# +# // 常量未使用大写 +# static final int maxRetry = 3; +# static final String DbHost = "localhost"; +# +# // 布尔变量无前缀 +# let active = true; +# function check(): boolean { ... } +# +# 正确做法: +# +# static final int MAX_RETRY = 3; +# static final String DB_HOST = "localhost"; +# +# let isActive = true; +# function canCheck(): boolean { ... } +# + +- id: require-constant-case + severity: warning + description: 常量命名必须使用全大写加下划线(SCREAMING_SNAKE_CASE) + message: 常量应使用全大写命名,如 MAX_RETRY_COUNT + languages: [javascript, typescript, java] + +- id: require-boolean-prefix + severity: info + description: 布尔变量和方法名应以 is/has/can/should 开头 + message: 布尔变量建议添加 is/has/can/should 前缀以提升可读性 + languages: [javascript, typescript] + +# ── 性能类 ────────────────────────────────────────────────────────── +# +# 架构说明: +# 订单服务采用 CQRS 模式,写操作走主库,读操作走从库。 +# 在高并发场景下,以下性能规范尤为重要。 +# +# 反面示例: +# +# // O(n³) 的订单匹配逻辑 +# for (const order of orders) { +# for (const item of order.items) { +# for (const warehouse of warehouses) { +# // 匹配逻辑... +# } +# } +# } +# +# 正确做法: +# +# const warehouseMap = new Map(warehouses.map(w => [w.id, w])); +# for (const order of orders) { +# for (const item of order.items) { +# const wh = warehouseMap.get(item.warehouseId); +# } +# } +# + +- id: no-nested-loops-deep + severity: warning + description: 禁止三层及以上嵌套循环,时间复杂度过高 + message: 检测到深层嵌套循环(≥3层),建议重构为扁平结构或使用查找表优化 + languages: [javascript, typescript, java] + +- id: no-sync-in-async + severity: warning + description: 异步函数内禁止调用同步阻塞 API + message: 在 async 函数中调用同步 API 会阻塞事件循环,请改用异步版本 + languages: [javascript, typescript] + +# ── 代码风格类 ────────────────────────────────────────────────────── +# +# 反面示例: +# +# // 无类型注解 +# function createOrder(data) { +# return api.post('/orders', data); +# } +# +# // 魔法数字 +# if (order.status === 3) { ... } +# setTimeout(retry, 5000); +# +# 正确做法: +# +# function createOrder(data: CreateOrderDTO): Promise { +# return api.post('/orders', data); +# } +# +# const ORDER_STATUS_SHIPPED = 3; +# const RETRY_DELAY_MS = 5000; +# if (order.status === ORDER_STATUS_SHIPPED) { ... } +# setTimeout(retry, RETRY_DELAY_MS); +# + +- id: require-type-annotation + severity: info + description: 函数参数和返回值应显式标注 TypeScript 类型 + message: 建议为函数添加显式类型注解,提升类型安全性 + languages: [typescript] + +- id: no-magic-numbers + severity: info + description: 禁止在代码中直接使用魔法数字,应提取为命名常量 + message: 检测到魔法数字,建议提取为具名常量以提升可维护性 + languages: [javascript, typescript] + +# ── 团队约定类 ────────────────────────────────────────────────────── +# +# 部署流程说明: +# 每周二、四发布,发布窗口 14:00-16:00。 +# +# 反面示例: +# +# throw new RuntimeException("失败"); +# throw new Error("error"); +# +# 正确做法: +# +# throw new OrderNotFoundException("订单不存在, orderId=" + orderId); +# throw new PaymentFailedException("支付失败", cause); +# +# 版本历史: +# v1.0 2026-06-01 张三 初版 +# v1.1 2026-07-15 李四 新增性能规范 +# v1.2 2026-08-01 王五 补充代码示例 +# + +- id: require-error-context + severity: warning + description: throw 语句必须携带错误上下文信息 + message: throw 时应提供足够的上下文信息,便于问题定位 + languages: [javascript, typescript, java] + +- id: no-todo-in-production + severity: info + description: 生产代码中不应遗留 TODO/FIXME/HACK 注释 + message: 代码中发现 TODO/FIXME/HACK 注释,请在发布前处理 + excludeLanguages: [sql] + +- id: require-function-doc + severity: info + description: 公共函数应添加文档注释(JSDoc / Javadoc) + message: 公共函数缺少文档注释,建议补充说明用途、参数和返回值 + languages: [javascript, typescript, java] diff --git a/data/import-verification/03-irregular-content/team-coding-rules-multi-sheet.xlsx b/data/import-verification/03-irregular-content/team-coding-rules-multi-sheet.xlsx new file mode 100644 index 0000000..051cf97 Binary files /dev/null and b/data/import-verification/03-irregular-content/team-coding-rules-multi-sheet.xlsx differ diff --git a/data/import-verification/03-irregular-content/team-coding-rules.docx b/data/import-verification/03-irregular-content/team-coding-rules.docx new file mode 100644 index 0000000..c7e629a Binary files /dev/null and b/data/import-verification/03-irregular-content/team-coding-rules.docx differ diff --git a/data/import-verification/03-irregular-content/team-coding-rules.md b/data/import-verification/03-irregular-content/team-coding-rules.md new file mode 100644 index 0000000..9378f82 --- /dev/null +++ b/data/import-verification/03-irregular-content/team-coding-rules.md @@ -0,0 +1,284 @@ +# 电商订单管理系统 — 工程规范文档 + +> 本文档由订单研发团队维护,最后更新于 2026 年 7 月。 + +## 项目背景 + +本项目是一个面向 B 端商家的电商订单管理系统,日均订单量约 50 万单。系统采用微服务架构,包含订单服务、支付服务、库存服务和物流服务四个核心模块。 + +技术栈: +- 后端:Java 17 + Spring Boot 3.2 + MyBatis-Plus +- 前端:React 18 + TypeScript 5.3 + Vite +- 数据库:MySQL 8.0 + Redis 7 +- 消息队列:RocketMQ 5.x + +## 团队介绍 + +订单研发团队目前有 12 人: +- 后端 6 人(含 1 名 Tech Lead) +- 前端 3 人 +- QA 2 人 +- DevOps 1 人 + +团队代码仓库:`git@company.com:order-team/oms.git` + +## 一、安全相关规范 + +在 2026 Q2 的安全审计中,我们发现线上代码中存在硬编码的数据库密码,导致一次严重的安全事件。因此制定以下规范: + +### 1.1 禁止硬编码凭证 + +severity: error +适用语言:JavaScript、TypeScript、Java + +禁止在源码中硬编码密码、令牌、API Key 等敏感凭证。检测到疑似硬编码凭证时,请使用环境变量或密钥管理服务注入。 + +以下是一个**反面示例**(请勿模仿): + +```java +// ❌ 错误做法 +public class DatabaseConfig { + private String password = "Admin@123456"; + private String apiKey = "sk-abc123xyz"; +} + +// ✅ 正确做法 +public class DatabaseConfig { + @Value("${db.password}") + private String password; + + @Value("${api.key}") + private String apiKey; +} +``` + +### 1.2 禁止使用 eval() + +severity: error +适用语言:JavaScript、TypeScript + +上周代码审查中发现前端模块有 `eval()` 调用,存在代码注入风险。eval() 存在安全风险,请使用 JSON.parse() 或 Function 构造器替代。 + +```javascript +// ❌ 错误:使用 eval 解析用户输入 +const data = eval(request.body); + +// ✅ 正确:使用 JSON.parse +const data = JSON.parse(request.body); +``` + +### 1.3 禁止直接赋值 innerHTML + +severity: warning + +这是一条通用规则,适用于所有语言(因为各端都可能涉及 DOM 操作)。避免直接操作 innerHTML,请使用 textContent 或 DOMPurify 清洗。 + +相关讨论参见 [内部 Wiki: XSS 防护指南](https://wiki.internal/security/xss) + +## 二、命名规范 + +> 以下命名规范参考了 Google Java Style Guide 和 Airbnb JavaScript Style Guide,根据团队实际情况做了调整。 + +### 2.1 常量命名 + +severity: warning +适用语言:JavaScript、TypeScript、Java + +常量命名必须使用全大写加下划线(SCREAMING_SNAKE_CASE)。常量应使用全大写命名,如 MAX_RETRY_COUNT。 + +```java +// ❌ 错误 +static final int maxRetry = 3; +static final String DbHost = "localhost"; + +// ✅ 正确 +static final int MAX_RETRY = 3; +static final String DB_HOST = "localhost"; +``` + +### 2.2 布尔变量前缀 + +severity: info +适用语言:JavaScript、TypeScript + +布尔变量和方法名应以 is/has/can/should 开头。布尔变量建议添加 is/has/can/should 前缀以提升可读性。 + +```typescript +// ❌ 错误 +let active = true; +let user = { verified: true }; +function check(): boolean { ... } + +// ✅ 正确 +let isActive = true; +let user = { isVerified: true }; +function canCheck(): boolean { ... } +``` + +## 三、性能规范 + +### 架构说明 + +订单服务采用 CQRS 模式,写操作走主库,读操作走从库。在高并发场景下,以下性能规范尤为重要。 + +### 3.1 禁止深层嵌套循环 + +severity: warning +适用语言:JavaScript、TypeScript、Java + +禁止三层及以上嵌套循环,时间复杂度过高。检测到深层嵌套循环(≥3层)时,建议重构为扁平结构或使用查找表优化。 + +```javascript +// ❌ 错误:O(n³) 的订单匹配逻辑 +for (const order of orders) { + for (const item of order.items) { + for (const warehouse of warehouses) { + // 匹配逻辑... + } + } +} + +// ✅ 正确:使用 Map 优化为 O(n) +const warehouseMap = new Map(warehouses.map(w => [w.id, w])); +for (const order of orders) { + for (const item of order.items) { + const wh = warehouseMap.get(item.warehouseId); + } +} +``` + +### 3.2 异步函数内禁止同步 API + +severity: warning +适用语言:JavaScript、TypeScript + +异步函数内禁止调用同步阻塞 API。在 async 函数中调用同步 API 会阻塞事件循环,请改用异步版本。 + +### 2026-07-15 会议纪要 + +- 讨论了 Node.js 事件循环阻塞问题 +- 决定在 async 函数中全面禁用 fs.readFileSync 等同步 API +- 下个 Sprint 开始 Code Review 时执行 + +## 四、代码风格 + +### 4.1 函数显式类型注解 + +severity: info +适用语言:TypeScript + +函数参数和返回值应显式标注 TypeScript 类型。建议为函数添加显式类型注解,提升类型安全性。 + +```typescript +// ❌ 错误 +function createOrder(data) { + return api.post('/orders', data); +} + +// ✅ 正确 +function createOrder(data: CreateOrderDTO): Promise { + return api.post('/orders', data); +} +``` + +### 4.2 禁止魔法数字 + +severity: info +适用语言:JavaScript、TypeScript + +禁止在代码中直接使用魔法数字,应提取为命名常量。检测到魔法数字,建议提取为具名常量以提升可维护性。 + +```javascript +// ❌ 错误 +if (order.status === 3) { ... } +setTimeout(retry, 5000); + +// ✅ 正确 +const ORDER_STATUS_SHIPPED = 3; +const RETRY_DELAY_MS = 5000; +if (order.status === ORDER_STATUS_SHIPPED) { ... } +setTimeout(retry, RETRY_DELAY_MS); +``` + +## 五、团队约定 + +### 部署流程说明 + +部署流程参考 CI/CD Pipeline 文档。每周二、四发布,发布窗口为 14:00-16:00。 + +### 5.1 throw 语句携带上下文 + +severity: warning +适用语言:JavaScript、TypeScript、Java + +throw 语句必须携带错误上下文信息。throw 时应提供足够的上下文信息,便于问题定位。 + +```java +// ❌ 错误 +throw new RuntimeException("失败"); +throw new Error("error"); + +// ✅ 正确 +throw new OrderNotFoundException("订单不存在, orderId=" + orderId); +throw new PaymentFailedException("支付失败", cause); +``` + +### 5.2 禁止遗留 TODO 注释 + +severity: info +排除语言:SQL + +生产代码中不应遗留 TODO/FIXME/HACK 注释。代码中发现 TODO/FIXME/HACK 注释,请在发布前处理。 + +> 注:SQL 脚本中允许临时性的 TODO 标记,因为数据库迁移脚本的生命周期与代码不同。 + +### 5.3 公共函数文档注释 + +severity: info +适用语言:JavaScript、TypeScript、Java + +公共函数应添加文档注释(JSDoc / Javadoc)。公共函数缺少文档注释,建议补充说明用途、参数和返回值。 + +```java +/** + * 创建订单 + * @param request 订单创建请求 + * @return 订单创建结果 + * @throws InsufficientStockException 库存不足时抛出 + */ +public OrderResult createOrder(CreateOrderRequest request) { ... } +``` + +```typescript +/** + * 获取用户订单列表 + * @param userId 用户ID + * @param page 分页参数 + * @returns 订单列表 + */ +function getUserOrders(userId: string, page: Pagination): Promise { ... } +``` + +## 附录 + +### A. 代码审查 Checklist + +- [ ] 安全规范是否遵守 +- [ ] 命名规范是否一致 +- [ ] 性能是否有明显瓶颈 +- [ ] 代码风格是否统一 +- [ ] 团队约定是否遵循 + +### B. 相关链接 + +- [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html) +- [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript) +- [TypeScript ESLint Rules](https://typescript-eslint.io/rules/) + +### C. 版本历史 + +| 版本 | 日期 | 作者 | 变更说明 | +|------|------|------|----------| +| 1.0 | 2026-06-01 | 张三 | 初版 | +| 1.1 | 2026-07-15 | 李四 | 新增性能规范 | +| 1.2 | 2026-08-01 | 王五 | 补充代码示例 | diff --git a/data/import-verification/03-irregular-content/team-coding-rules.pptx b/data/import-verification/03-irregular-content/team-coding-rules.pptx new file mode 100644 index 0000000..d0b19bb Binary files /dev/null and b/data/import-verification/03-irregular-content/team-coding-rules.pptx differ diff --git a/data/import-verification/03-irregular-content/team-coding-rules.txt b/data/import-verification/03-irregular-content/team-coding-rules.txt new file mode 100644 index 0000000..e25244b --- /dev/null +++ b/data/import-verification/03-irregular-content/team-coding-rules.txt @@ -0,0 +1,287 @@ +电商订单管理系统 — 工程规范文档 +团队:订单研发团队(后端6人 + 前端3人 + QA2人 + DevOps1人) +最后更新:2026-07-15 +仓库:git@company.com:order-team/oms.git + +================================================================================ +项目背景 +================================================================================ + +本项目是一个面向 B 端商家的电商订单管理系统,日均订单量约 50 万单。 +系统采用微服务架构,包含订单服务、支付服务、库存服务和物流服务四个核心模块。 + +技术栈: +- 后端:Java 17 + Spring Boot 3.2 + MyBatis-Plus +- 前端:React 18 + TypeScript 5.3 + Vite +- 数据库:MySQL 8.0 + Redis 7 +- 消息队列:RocketMQ 5.x + +================================================================================ +团队介绍 +================================================================================ + +订单研发团队目前有 12 人: +- 后端 6 人(含 1 名 Tech Lead:张三) +- 前端 3 人(负责人:李四) +- QA 2 人 +- DevOps 1 人 + +团队代码仓库:git@company.com:order-team/oms.git +内部 Wiki:https://wiki.internal/order-team + +================================================================================ +一、安全相关规范 +================================================================================ + +在 2026 Q2 的安全审计中,我们发现线上代码中存在硬编码的数据库密码, +导致一次严重的安全事件。因此制定以下规范: + +---- 规则 ---- +名称:禁止硬编码凭证 +严重级别:error +适用语言:javascript, typescript, java +描述:禁止在源码中硬编码密码、令牌、API Key 等敏感凭证 +提示:检测到疑似硬编码凭证,请使用环境变量或密钥管理服务注入 + +以下是反面示例(请勿模仿): + + // Java: 硬编码密码 + public class DatabaseConfig { + private String password = "Admin@123456"; + private String apiKey = "sk-abc123xyz"; + } + + // JavaScript: 硬编码 Token + const API_TOKEN = "ghp_abc123def456"; + +正确做法: + + @Value("${db.password}") + private String password; + + const apiToken = process.env.API_TOKEN; + +---- 规则 ---- +名称:禁止使用 eval() +严重级别:error +适用语言:javascript, typescript +描述:禁止使用 eval() 函数,存在代码注入风险 +提示:eval() 存在安全风险,请使用 JSON.parse() 或 Function 构造器替代 + +上周代码审查中发现前端模块有 eval() 调用: + + // 错误:使用 eval 解析用户输入 + const data = eval(request.body); + + // 正确:使用 JSON.parse + const data = JSON.parse(request.body); + +---- 规则 ---- +名称:禁止直接赋值 innerHTML +严重级别:warning +适用语言:所有语言 +描述:禁止直接赋值 innerHTML,可能导致 XSS +提示:避免直接操作 innerHTML,请使用 textContent 或 DOMPurify 清洗 + +相关讨论参见内部 Wiki: XSS 防护指南 + +================================================================================ +二、命名规范 +================================================================================ + +以下命名规范参考了 Google Java Style Guide 和 Airbnb JavaScript Style Guide, +根据团队实际情况做了调整。 + +---- 规则 ---- +名称:常量使用全大写命名 +严重级别:warning +适用语言:javascript, typescript, java +描述:常量命名必须使用全大写加下划线(SCREAMING_SNAKE_CASE) +提示:常量应使用全大写命名,如 MAX_RETRY_COUNT + +反面示例: + + static final int maxRetry = 3; + static final String DbHost = "localhost"; + +正确做法: + + static final int MAX_RETRY = 3; + static final String DB_HOST = "localhost"; + +---- 规则 ---- +名称:布尔变量添加前缀 +严重级别:info +适用语言:javascript, typescript +描述:布尔变量和方法名应以 is/has/can/should 开头 +提示:布尔变量建议添加 is/has/can/should 前缀以提升可读性 + + // 错误 + let active = true; + let user = { verified: true }; + function check(): boolean { ... } + + // 正确 + let isActive = true; + let user = { isVerified: true }; + function canCheck(): boolean { ... } + +================================================================================ +三、性能规范 +================================================================================ + +架构说明:订单服务采用 CQRS 模式,写操作走主库,读操作走从库。 +在高并发场景下,以下性能规范尤为重要。 + +---- 规则 ---- +名称:禁止三层以上嵌套循环 +严重级别:warning +适用语言:javascript, typescript, java +描述:禁止三层及以上嵌套循环,时间复杂度过高 +提示:检测到深层嵌套循环(≥3层),建议重构为扁平结构或使用查找表优化 + + // 错误:O(n³) 的订单匹配逻辑 + for (const order of orders) { + for (const item of order.items) { + for (const warehouse of warehouses) { + // 匹配逻辑... + } + } + } + + // 正确:使用 Map 优化为 O(n) + const warehouseMap = new Map(warehouses.map(w => [w.id, w])); + for (const order of orders) { + for (const item of order.items) { + const wh = warehouseMap.get(item.warehouseId); + } + } + +---- 规则 ---- +名称:异步函数内禁止同步 API +严重级别:warning +适用语言:javascript, typescript +描述:异步函数内禁止调用同步阻塞 API +提示:在 async 函数中调用同步 API 会阻塞事件循环,请改用异步版本 + +--- 2026-07-15 会议纪要 --- + +- 讨论了 Node.js 事件循环阻塞问题 +- 决定在 async 函数中全面禁用 fs.readFileSync 等同步 API +- 下个 Sprint 开始 Code Review 时执行 +- 张三负责更新 ESLint 配置 +- 李四负责前端代码排查 + +================================================================================ +四、代码风格 +================================================================================ + +---- 规则 ---- +名称:函数显式类型注解 +严重级别:info +适用语言:typescript +描述:函数参数和返回值应显式标注 TypeScript 类型 +提示:建议为函数添加显式类型注解,提升类型安全性 + + // 错误 + function createOrder(data) { + return api.post('/orders', data); + } + + // 正确 + function createOrder(data: CreateOrderDTO): Promise { + return api.post('/orders', data); + } + +---- 规则 ---- +名称:禁止魔法数字 +严重级别:info +适用语言:javascript, typescript +描述:禁止在代码中直接使用魔法数字,应提取为命名常量 +提示:检测到魔法数字,建议提取为具名常量以提升可维护性 + + // 错误 + if (order.status === 3) { ... } + setTimeout(retry, 5000); + + // 正确 + const ORDER_STATUS_SHIPPED = 3; + const RETRY_DELAY_MS = 5000; + if (order.status === ORDER_STATUS_SHIPPED) { ... } + setTimeout(retry, RETRY_DELAY_MS); + +================================================================================ +五、团队约定 +================================================================================ + +部署流程说明: + 每周二、四发布,发布窗口 14:00-16:00。 + CI/CD Pipeline 详见 Jenkins 配置。 + +---- 规则 ---- +名称:throw 语句携带上下文 +严重级别:warning +适用语言:javascript, typescript, java +描述:throw 语句必须携带错误上下文信息 +提示:throw 时应提供足够的上下文信息,便于问题定位 + + // 错误 + throw new RuntimeException("失败"); + throw new Error("error"); + + // 正确 + throw new OrderNotFoundException("订单不存在, orderId=" + orderId); + throw new PaymentFailedException("支付失败", cause); + +---- 规则 ---- +名称:禁止遗留 TODO 注释 +严重级别:info +排除语言:sql +描述:生产代码中不应遗留 TODO/FIXME/HACK 注释 +提示:代码中发现 TODO/FIXME/HACK 注释,请在发布前处理 + +注:SQL 脚本中允许临时性的 TODO 标记,因为数据库迁移脚本的生命周期与代码不同。 + +---- 规则 ---- +名称:公共函数文档注释 +严重级别:info +适用语言:javascript, typescript, java +描述:公共函数应添加文档注释(JSDoc / Javadoc) +提示:公共函数缺少文档注释,建议补充说明用途、参数和返回值 + + /** + * 创建订单 + * @param request 订单创建请求 + * @return 订单创建结果 + * @throws InsufficientStockException 库存不足时抛出 + */ + public OrderResult createOrder(CreateOrderRequest request) { ... } + + /** + * 获取用户订单列表 + * @param userId 用户ID + * @param page 分页参数 + * @returns 订单列表 + */ + function getUserOrders(userId: string, page: Pagination): Promise { ... } + +================================================================================ +附录 +================================================================================ + +A. 代码审查 Checklist + [ ] 安全规范是否遵守 + [ ] 命名规范是否一致 + [ ] 性能是否有明显瓶颈 + [ ] 代码风格是否统一 + [ ] 团队约定是否遵循 + +B. 相关链接 + - Google Java Style Guide: https://google.github.io/styleguide/javaguide.html + - Airbnb JavaScript Style Guide: https://github.com/airbnb/javascript + - TypeScript ESLint Rules: https://typescript-eslint.io/rules/ + +C. 版本历史 + v1.0 2026-06-01 张三 初版 + v1.1 2026-07-15 李四 新增性能规范 + v1.2 2026-08-01 王五 补充代码示例 diff --git a/data/import-verification/03-irregular-content/team-coding-rules.xlsx b/data/import-verification/03-irregular-content/team-coding-rules.xlsx new file mode 100644 index 0000000..674d205 Binary files /dev/null and b/data/import-verification/03-irregular-content/team-coding-rules.xlsx differ diff --git a/data/import-verification/03-irregular-content/team-coding-rules.yaml b/data/import-verification/03-irregular-content/team-coding-rules.yaml new file mode 100644 index 0000000..bbbe8ea --- /dev/null +++ b/data/import-verification/03-irregular-content/team-coding-rules.yaml @@ -0,0 +1,225 @@ +# ┌─────────────────────────────────────────────────────────────────┐ +# │ 电商订单管理系统 — 工程规范文档 │ +# │ 团队:订单研发团队(后端6人 + 前端3人 + QA2人 + DevOps1人) │ +# │ 最后更新:2026-07-15 │ +# │ 仓库:git@company.com:order-team/oms.git │ +# └─────────────────────────────────────────────────────────────────┘ +# +# 项目背景: +# 面向 B 端商家的电商订单管理系统,日均订单量约 50 万单。 +# 微服务架构:订单服务、支付服务、库存服务、物流服务。 +# 技术栈:Java 17 + Spring Boot 3.2 + React 18 + TypeScript 5.3 +# +# 架构说明: +# 订单服务采用 CQRS 模式,写操作走主库,读操作走从库。 +# 消息队列使用 RocketMQ 5.x。 +# +# 2026-07-15 会议纪要: +# - 讨论了 Node.js 事件循环阻塞问题 +# - 决定在 async 函数中全面禁用 fs.readFileSync 等同步 API +# - 下个 Sprint 开始 Code Review 时执行 +# +# 部署流程: +# 每周二、四发布,发布窗口 14:00-16:00。 +# CI/CD Pipeline 详见 Jenkins 配置。 +# +# 代码审查 Checklist: +# [ ] 安全规范是否遵守 +# [ ] 命名规范是否一致 +# [ ] 性能是否有明显瓶颈 +# [ ] 代码风格是否统一 +# [ ] 团队约定是否遵循 +# +# ── 安全类 ────────────────────────────────────────────────────────── +# +# 反面示例(请勿模仿): +# +# // Java: 硬编码密码 +# public class DatabaseConfig { +# private String password = "Admin@123456"; +# } +# +# // JavaScript: 使用 eval +# const data = eval(request.body); +# +# // JavaScript: innerHTML 赋值 +# element.innerHTML = userInput; +# +# 正确做法: +# +# @Value("${db.password}") +# private String password; +# +# const data = JSON.parse(request.body); +# +# element.textContent = userInput; +# + +- id: no-hardcoded-credentials + severity: error + description: 禁止在源码中硬编码密码、令牌、API Key 等敏感凭证 + message: 检测到疑似硬编码凭证,请使用环境变量或密钥管理服务注入 + languages: [javascript, typescript, java] + +- id: no-eval-usage + severity: error + description: 禁止使用 eval() 函数,存在代码注入风险 + message: eval() 存在安全风险,请使用 JSON.parse() 或 Function 构造器替代 + languages: [javascript, typescript] + +- id: no-innerhtml-assignment + severity: warning + description: 禁止直接赋值 innerHTML,可能导致 XSS + message: 避免直接操作 innerHTML,请使用 textContent 或 DOMPurify 清洗 + +# ── 命名规范类 ────────────────────────────────────────────────────── +# +# 参考规范: +# - Google Java Style Guide +# - Airbnb JavaScript Style Guide +# +# 反面示例: +# +# // 常量未使用大写 +# static final int maxRetry = 3; +# static final String DbHost = "localhost"; +# +# // 布尔变量无前缀 +# let active = true; +# function check(): boolean { ... } +# +# 正确做法: +# +# static final int MAX_RETRY = 3; +# static final String DB_HOST = "localhost"; +# +# let isActive = true; +# function canCheck(): boolean { ... } +# + +- id: require-constant-case + severity: warning + description: 常量命名必须使用全大写加下划线(SCREAMING_SNAKE_CASE) + message: 常量应使用全大写命名,如 MAX_RETRY_COUNT + languages: [javascript, typescript, java] + +- id: require-boolean-prefix + severity: info + description: 布尔变量和方法名应以 is/has/can/should 开头 + message: 布尔变量建议添加 is/has/can/should 前缀以提升可读性 + languages: [javascript, typescript] + +# ── 性能类 ────────────────────────────────────────────────────────── +# +# 架构说明: +# 订单服务采用 CQRS 模式,写操作走主库,读操作走从库。 +# 在高并发场景下,以下性能规范尤为重要。 +# +# 反面示例: +# +# // O(n³) 的订单匹配逻辑 +# for (const order of orders) { +# for (const item of order.items) { +# for (const warehouse of warehouses) { +# // 匹配逻辑... +# } +# } +# } +# +# 正确做法: +# +# const warehouseMap = new Map(warehouses.map(w => [w.id, w])); +# for (const order of orders) { +# for (const item of order.items) { +# const wh = warehouseMap.get(item.warehouseId); +# } +# } +# + +- id: no-nested-loops-deep + severity: warning + description: 禁止三层及以上嵌套循环,时间复杂度过高 + message: 检测到深层嵌套循环(≥3层),建议重构为扁平结构或使用查找表优化 + languages: [javascript, typescript, java] + +- id: no-sync-in-async + severity: warning + description: 异步函数内禁止调用同步阻塞 API + message: 在 async 函数中调用同步 API 会阻塞事件循环,请改用异步版本 + languages: [javascript, typescript] + +# ── 代码风格类 ────────────────────────────────────────────────────── +# +# 反面示例: +# +# // 无类型注解 +# function createOrder(data) { +# return api.post('/orders', data); +# } +# +# // 魔法数字 +# if (order.status === 3) { ... } +# setTimeout(retry, 5000); +# +# 正确做法: +# +# function createOrder(data: CreateOrderDTO): Promise { +# return api.post('/orders', data); +# } +# +# const ORDER_STATUS_SHIPPED = 3; +# const RETRY_DELAY_MS = 5000; +# if (order.status === ORDER_STATUS_SHIPPED) { ... } +# setTimeout(retry, RETRY_DELAY_MS); +# + +- id: require-type-annotation + severity: info + description: 函数参数和返回值应显式标注 TypeScript 类型 + message: 建议为函数添加显式类型注解,提升类型安全性 + languages: [typescript] + +- id: no-magic-numbers + severity: info + description: 禁止在代码中直接使用魔法数字,应提取为命名常量 + message: 检测到魔法数字,建议提取为具名常量以提升可维护性 + languages: [javascript, typescript] + +# ── 团队约定类 ────────────────────────────────────────────────────── +# +# 部署流程说明: +# 每周二、四发布,发布窗口 14:00-16:00。 +# +# 反面示例: +# +# throw new RuntimeException("失败"); +# throw new Error("error"); +# +# 正确做法: +# +# throw new OrderNotFoundException("订单不存在, orderId=" + orderId); +# throw new PaymentFailedException("支付失败", cause); +# +# 版本历史: +# v1.0 2026-06-01 张三 初版 +# v1.1 2026-07-15 李四 新增性能规范 +# v1.2 2026-08-01 王五 补充代码示例 +# + +- id: require-error-context + severity: warning + description: throw 语句必须携带错误上下文信息 + message: throw 时应提供足够的上下文信息,便于问题定位 + languages: [javascript, typescript, java] + +- id: no-todo-in-production + severity: info + description: 生产代码中不应遗留 TODO/FIXME/HACK 注释 + message: 代码中发现 TODO/FIXME/HACK 注释,请在发布前处理 + excludeLanguages: [sql] + +- id: require-function-doc + severity: info + description: 公共函数应添加文档注释(JSDoc / Javadoc) + message: 公共函数缺少文档注释,建议补充说明用途、参数和返回值 + languages: [javascript, typescript, java] diff --git a/data/import-verification/guide.md b/data/import-verification/guide.md new file mode 100644 index 0000000..bcf7757 --- /dev/null +++ b/data/import-verification/guide.md @@ -0,0 +1,28 @@ +# 自定义规则导入验证 — 目录导航 + +本目录按测试场景分类组织。每个场景独立存放素材、结果与报告,互不干扰、互不覆盖。 + +## 场景结构 + +| 目录 | 场景 | 状态 | +|---|---|---| +| `01-galaxy-nonstandard/` | 真实世界非标准格式(双 Sheet、无标准表头、含干扰段落) | ✅ 已完成,报告在内 | +| `02-standard-formats/` | 标准格式矩阵(同一规则集 8 种格式逐一导入) | ✅ 已完成,报告在内 | +| `03-irregular-content/` | 不规则规则内容(重噪声嵌入,7 种格式) | ✅ 已完成,报告在内 | + +每个场景目录内的约定: + +- 素材文件直接放在场景根目录 +- 导入结果(从 `.code-review/rules/` 移出的 yaml)统一放 `results/` 子目录 +- `result-report.md` 为该场景的验证结果报告 + +## 规则命名约定(防覆盖) + +| 场景 | 规则名格式 | 示例 | +|---|---|---| +| 02 标准格式 | `standard-rules-<格式>` | `standard-rules-md` | +| 03 不规则内容 | `irregular-<格式>` | `irregular-md` | + +- 导入时插件拒绝覆盖 `.code-review/rules/` 下的同名规则文件,前缀错开即无冲突 +- 每轮验证核对完成后,及时把结果 yaml 从 `.code-review/rules/` 移入对应场景的 `results/` 归档 +- `tests/fixtures/` 下的素材副本是自动化测试依赖,与本目录素材无关,勿混用