@spaceflow/review 1.0.0 → 3.0.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## [2.0.0](https://github.com/Lydanne/spaceflow/compare/@spaceflow/review@1.0.0...@spaceflow/review@2.0.0) (2026-04-13)
+
+### 代码重构
+
+* **review:** 优化 Example 标题和描述解析逻辑 ([decb54f](https://github.com/Lydanne/spaceflow/commit/decb54f6832acaeddd83ccfb6a3439c47294f11d))
+
+### 其他修改
+
+* **review-summary:** released version 1.0.0 [no ci] ([742d53e](https://github.com/Lydanne/spaceflow/commit/742d53efb7f16e33c50d9b1c4b9e31a7c0e8da21))
+
+## [1.0.0](https://github.com/Lydanne/spaceflow/compare/@spaceflow/review@0.83.0...@spaceflow/review@1.0.0) (2026-04-13)
+
+### ⚠ BREAKING CHANGES
+
+* **review:** 重构 example 数据结构,支持 `### Example:` 分组和 `#### Good:/Bad:` 标题语法
+
+### 新特性
+
+* **review:** 新增 includes 变更类型前缀语法支持 ([2f5655f](https://github.com/Lydanne/spaceflow/commit/2f5655fc414828ea3a0269fba04611d2bf2591a9))
+* **review:** 重构 example 数据结构,支持 `### Example:` 分组和 `#### Good:/Bad:` 标题语法 ([e45bd5a](https://github.com/Lydanne/spaceflow/commit/e45bd5aab5e317b8f70a8b107c17aab6548c3296))
+
+### 其他修改
+
+* **review-summary:** released version 0.52.0 [no ci] ([1d0cdac](https://github.com/Lydanne/spaceflow/commit/1d0cdacdbe12db98399e69fd53bbfdd23825cc10))
+
 ## [0.83.0](https://github.com/Lydanne/spaceflow/compare/@spaceflow/review@0.82.0...@spaceflow/review@0.83.0) (2026-04-10)
 
 ### 代码重构

package/dist/index.js

@@ -305,7 +305,7 @@ const CODE_BLOCK_TYPES = [
 function formatExample(example) {
     let text = "";
     if (example.title) {
-        text += `##### ${example.title}\n`;
+        text += `##### Example: ${example.title}\n`;
     }
     if (example.description) {
         text += `${example.description}\n`;
@@ -903,13 +903,18 @@ class ReviewSpecService {
         for (const groupSection of groupSections){
             const trimmedGroup = groupSection.trim();
             if (!trimmedGroup) continue;
-            // 提取分组描述，如 "### Example: 命名规则说明"
+            // 提取分组标题和描述，如 "### Example: 函数行数"
             let exampleTitle = "";
             let exampleDescription = "";
             const groupMatch = trimmedGroup.match(/^###\s+Example\s*[:：]\s*(.+)/i);
             if (groupMatch) {
-                exampleTitle = "Example";
-                exampleDescription = groupMatch[1].trim();
+                exampleTitle = groupMatch[1].trim();
+                // 提取标题行和第一个 #### 之间的文本作为 description
+                const afterTitle = trimmedGroup.slice(trimmedGroup.indexOf("\n")).trim();
+                const firstSubIdx = afterTitle.search(/(?:^|\n)####\s+/);
+                if (firstSubIdx > 0) {
+                    exampleDescription = afterTitle.slice(0, firstSubIdx).trim();
+                }
             }
             // 在分组内按 #### 提取 Good/Bad
             const ruleContents = [];
@@ -983,12 +988,12 @@ class ReviewSpecService {
    * 如果 spec 没有 includes 配置，则保留该 spec 的所有 issues
    * 支持 `added|`/`modified|`/`deleted|` 前缀语法
    */ filterIssuesByIncludes(issues, specs, changedFiles) {
-        // 构建 spec filename -> includes 的映射
+        // 构建 rule.id -> includes 的映射（规则级优先，文件级兜底）
         const specIncludesMap = new Map();
         for (const spec of specs){
-            // 从规则 ID 前缀推断 spec filename
             for (const rule of spec.rules){
-                specIncludesMap.set(rule.id, spec.includes);
+                // 规则级 includes 覆盖文件级 includes，与 severity 优先级一致
+                specIncludesMap.set(rule.id, rule.includes ?? spec.includes);
             }
         }
         return issues.filter((issue)=>{

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spaceflow/review",
-  "version": "1.0.0",
+  "version": "3.0.0",
   "description": "Spaceflow 代码审查插件，使用 LLM 对 PR 代码进行自动审查",
   "license": "MIT",
   "author": "Lydanne",

package/src/prompt/specs-section.ts

@@ -31,7 +31,7 @@ export function buildSpecsSection(specs: ReviewSpec[]): string {
 function formatExample(example: RuleExample): string {
   let text = "";
   if (example.title) {
-    text += `##### ${example.title}\n`;
+    text += `##### Example: ${example.title}\n`;
   }
   if (example.description) {
     text += `${example.description}\n`;

package/src/review-spec/review-spec.service.spec.ts

@@ -1674,8 +1674,8 @@ const bad_name = 1;
     });
   });
 
-  describe("filterIssuesByIncludes - rule-level includes", () => {
-    it("should use rule-level includes for filtering", () => {
+  describe("filterIssuesByIncludes - includes priority", () => {
+    it("should use rule-level includes over file-level includes", () => {
       const specs = [
         {
           filename: "nest.md",
@@ -1706,12 +1706,301 @@ const bad_name = 1;
       ];
       const issues = [
         { file: "user.model.ts", ruleId: "JsTs.Nest.Model" },
+        { file: "order.model.ts", ruleId: "JsTs.Nest.Model" },
         { file: "user.controller.ts", ruleId: "JsTs.Nest" },
+        { file: "order.controller.ts", ruleId: "JsTs.Nest" },
+        { file: "user.service.ts", ruleId: "JsTs.Nest" },
+        { file: "user.module.ts", ruleId: "JsTs.Nest" },
+        { file: "user.model.ts", ruleId: "JsTs.Nest" }, // model 文件但 ruleId 是 Nest（文件级）
       ];
       const result = service.filterIssuesByIncludes(issues, specs);
-      // spec.includes 是 *.controller.ts，user.model.ts 不匹配
-      expect(result).toHaveLength(1);
-      expect(result[0].file).toBe("user.controller.ts");
+      // JsTs.Nest.Model → 规则级 *.model.ts，user.model.ts / order.model.ts 匹配 → 保留
+      // JsTs.Nest → 文件级 *.controller.ts，user.controller.ts / order.controller.ts 匹配 → 保留
+      // user.service.ts / user.module.ts 不匹配文件级 *.controller.ts → 过滤
+      // user.model.ts(ruleId=Nest) → 文件级 *.controller.ts，不匹配 → 过滤
+      expect(result).toHaveLength(4);
+      expect(result.map((i) => i.file)).toEqual([
+        "user.model.ts",
+        "order.model.ts",
+        "user.controller.ts",
+        "order.controller.ts",
+      ]);
+    });
+
+    it("should fall back to file-level includes when rule has no includes", () => {
+      const specs = [
+        {
+          filename: "nest.md",
+          extensions: ["ts"],
+          type: "nest",
+          content: "",
+          overrides: [],
+          severity: "error" as const,
+          includes: ["*.controller.ts"],
+          rules: [
+            {
+              id: "JsTs.Nest",
+              title: "Nest",
+              description: "",
+              examples: [],
+              overrides: [],
+            },
+            {
+              id: "JsTs.Nest.DirStructure",
+              title: "DirStructure",
+              description: "",
+              examples: [],
+              overrides: [],
+              // 无 rule.includes → 回退到 spec.includes
+            },
+          ],
+        },
+      ];
+      const issues = [
+        { file: "user.controller.ts", ruleId: "JsTs.Nest.DirStructure" },
+        { file: "order.controller.ts", ruleId: "JsTs.Nest.DirStructure" },
+        { file: "user.service.ts", ruleId: "JsTs.Nest.DirStructure" },
+        { file: "user.module.ts", ruleId: "JsTs.Nest.DirStructure" },
+        { file: "user.controller.ts", ruleId: "JsTs.Nest" },
+        { file: "user.service.ts", ruleId: "JsTs.Nest" },
+      ];
+      const result = service.filterIssuesByIncludes(issues, specs);
+      // DirStructure 无规则级 includes → 回退文件级 *.controller.ts
+      // user.controller.ts / order.controller.ts 匹配 → 保留
+      // user.service.ts / user.module.ts 不匹配 → 过滤
+      // JsTs.Nest 同样回退文件级，user.controller.ts 匹配 → 保留，user.service.ts 不匹配 → 过滤
+      expect(result).toHaveLength(3);
+      expect(result.map((i) => i.file)).toEqual([
+        "user.controller.ts",
+        "order.controller.ts",
+        "user.controller.ts",
+      ]);
+    });
+
+    it("should use rule-level includes even when it narrows the file-level scope", () => {
+      const specs = [
+        {
+          filename: "js&ts.md",
+          extensions: ["ts"],
+          type: "base",
+          content: "",
+          overrides: [],
+          severity: "error" as const,
+          includes: ["*.ts"], // 文件级：所有 ts 文件
+          rules: [
+            {
+              id: "JsTs.Base",
+              title: "Base",
+              description: "",
+              examples: [],
+              overrides: [],
+            },
+            {
+              id: "JsTs.Base.TestRule",
+              title: "TestRule",
+              description: "",
+              examples: [],
+              overrides: [],
+              includes: ["*.spec.ts"], // 规则级：仅 spec 文件（收窄）
+            },
+          ],
+        },
+      ];
+      const issues = [
+        { file: "app.spec.ts", ruleId: "JsTs.Base.TestRule" },
+        { file: "utils.spec.ts", ruleId: "JsTs.Base.TestRule" },
+        { file: "app.ts", ruleId: "JsTs.Base.TestRule" },
+        { file: "utils.ts", ruleId: "JsTs.Base.TestRule" },
+        { file: "app.ts", ruleId: "JsTs.Base" },
+        { file: "utils.ts", ruleId: "JsTs.Base" },
+        { file: "app.spec.ts", ruleId: "JsTs.Base" },
+      ];
+      const result = service.filterIssuesByIncludes(issues, specs);
+      // JsTs.Base.TestRule → 规则级 *.spec.ts，app.spec.ts / utils.spec.ts 匹配 → 保留
+      // app.ts / utils.ts 不匹配 *.spec.ts → 过滤
+      // JsTs.Base → 文件级 *.ts，app.ts / utils.ts / app.spec.ts 匹配 → 保留
+      expect(result).toHaveLength(5);
+      expect(result.map((i) => i.file)).toEqual([
+        "app.spec.ts",
+        "utils.spec.ts",
+        "app.ts",
+        "utils.ts",
+        "app.spec.ts",
+      ]);
+    });
+
+    it("should use rule-level includes even when it widens the file-level scope", () => {
+      const specs = [
+        {
+          filename: "nest.md",
+          extensions: ["ts"],
+          type: "nest",
+          content: "",
+          overrides: [],
+          severity: "error" as const,
+          includes: ["*.controller.ts"], // 文件级：仅 controller
+          rules: [
+            {
+              id: "JsTs.Nest",
+              title: "Nest",
+              description: "",
+              examples: [],
+              overrides: [],
+            },
+            {
+              id: "JsTs.Nest.AllFiles",
+              title: "AllFiles",
+              description: "",
+              examples: [],
+              overrides: [],
+              includes: ["*.ts"], // 规则级：所有 ts 文件（放宽）
+            },
+          ],
+        },
+      ];
+      const issues = [
+        { file: "user.service.ts", ruleId: "JsTs.Nest.AllFiles" },
+        { file: "user.controller.ts", ruleId: "JsTs.Nest.AllFiles" },
+        { file: "user.module.ts", ruleId: "JsTs.Nest.AllFiles" },
+        { file: "user.controller.ts", ruleId: "JsTs.Nest" },
+        { file: "order.controller.ts", ruleId: "JsTs.Nest" },
+        { file: "user.service.ts", ruleId: "JsTs.Nest" },
+        { file: "user.module.ts", ruleId: "JsTs.Nest" },
+      ];
+      const result = service.filterIssuesByIncludes(issues, specs);
+      // JsTs.Nest.AllFiles → 规则级 *.ts，全部匹配 → 保留 3 个
+      // JsTs.Nest → 文件级 *.controller.ts，user.controller.ts / order.controller.ts 匹配 → 保留
+      // user.service.ts / user.module.ts 不匹配 → 过滤
+      expect(result).toHaveLength(5);
+      expect(result.map((i) => i.file)).toEqual([
+        "user.service.ts",
+        "user.controller.ts",
+        "user.module.ts",
+        "user.controller.ts",
+        "order.controller.ts",
+      ]);
+    });
+
+    it("should support status prefix in rule-level includes", () => {
+      const specs = [
+        {
+          filename: "nest.md",
+          extensions: ["ts"],
+          type: "nest",
+          content: "",
+          overrides: [],
+          severity: "error" as const,
+          includes: ["*.controller.ts"], // 文件级：无前缀
+          rules: [
+            {
+              id: "JsTs.Nest",
+              title: "Nest",
+              description: "",
+              examples: [],
+              overrides: [],
+            },
+            {
+              id: "JsTs.Nest.Model",
+              title: "Model",
+              description: "",
+              examples: [],
+              overrides: [],
+              includes: ["added|*.model.ts", "modified|*.dto.ts"], // 规则级：added 的 model + modified 的 dto
+            },
+          ],
+        },
+      ];
+      const changedFiles = {
+        getStatus: (file: string) => {
+          if (file === "user.model.ts") return "added";
+          if (file === "order.model.ts") return "modified";
+          if (file === "user.dto.ts") return "modified";
+          if (file === "order.dto.ts") return "added";
+          return "modified";
+        },
+      } as any;
+      const issues = [
+        { file: "user.model.ts", ruleId: "JsTs.Nest.Model" }, // added + *.model.ts → 匹配
+        { file: "order.model.ts", ruleId: "JsTs.Nest.Model" }, // modified + *.model.ts → 不匹配 added|
+        { file: "user.dto.ts", ruleId: "JsTs.Nest.Model" }, // modified + *.dto.ts → 匹配 modified|
+        { file: "order.dto.ts", ruleId: "JsTs.Nest.Model" }, // added + *.dto.ts → 不匹配 modified|
+        { file: "user.controller.ts", ruleId: "JsTs.Nest" }, // 文件级 *.controller.ts → 匹配
+        { file: "user.service.ts", ruleId: "JsTs.Nest" }, // 文件级 *.controller.ts → 不匹配
+      ];
+      const result = service.filterIssuesByIncludes(issues, specs, changedFiles);
+      expect(result).toHaveLength(3);
+      expect(result.map((i) => i.file)).toEqual([
+        "user.model.ts",
+        "user.dto.ts",
+        "user.controller.ts",
+      ]);
+
+      // 全部 modified 时，added|*.model.ts 不匹配，modified|*.dto.ts 匹配
+      const changedFiles2 = {
+        getStatus: () => "modified",
+      } as any;
+      const result2 = service.filterIssuesByIncludes(issues, specs, changedFiles2);
+      // user.model.ts: modified, added|*.model.ts 不匹配 → 过滤
+      // order.model.ts: modified, added|*.model.ts 不匹配 → 过滤
+      // user.dto.ts: modified, modified|*.dto.ts 匹配 → 保留
+      // order.dto.ts: modified, modified|*.dto.ts 匹配 → 保留
+      // user.controller.ts: 文件级匹配 → 保留
+      // user.service.ts: 文件级不匹配 → 过滤
+      expect(result2).toHaveLength(3);
+      expect(result2.map((i) => i.file)).toEqual([
+        "user.dto.ts",
+        "order.dto.ts",
+        "user.controller.ts",
+      ]);
+    });
+
+    it("should use empty rule-level includes to remove file-level restriction", () => {
+      const specs = [
+        {
+          filename: "nest.md",
+          extensions: ["ts"],
+          type: "nest",
+          content: "",
+          overrides: [],
+          severity: "error" as const,
+          includes: ["*.controller.ts"], // 文件级：仅 controller
+          rules: [
+            {
+              id: "JsTs.Nest",
+              title: "Nest",
+              description: "",
+              examples: [],
+              overrides: [],
+            },
+            {
+              id: "JsTs.Nest.Global",
+              title: "Global",
+              description: "",
+              examples: [],
+              overrides: [],
+              includes: [], // 规则级：空数组 = 无限制（覆盖文件级）
+            },
+          ],
+        },
+      ];
+      const issues = [
+        { file: "user.service.ts", ruleId: "JsTs.Nest.Global" },
+        { file: "user.controller.ts", ruleId: "JsTs.Nest.Global" },
+        { file: "user.module.ts", ruleId: "JsTs.Nest.Global" },
+        { file: "user.service.ts", ruleId: "JsTs.Nest" },
+        { file: "user.controller.ts", ruleId: "JsTs.Nest" },
+        { file: "user.module.ts", ruleId: "JsTs.Nest" },
+      ];
+      const result = service.filterIssuesByIncludes(issues, specs);
+      // JsTs.Nest.Global → 规则级 includes=[] (空=无限制)，全部保留 3 个
+      // JsTs.Nest → 文件级 *.controller.ts，仅 user.controller.ts 匹配 → 保留
+      expect(result).toHaveLength(4);
+      expect(result.map((i) => i.file)).toEqual([
+        "user.service.ts",
+        "user.controller.ts",
+        "user.module.ts",
+        "user.controller.ts",
+      ]);
     });
   });
 
@@ -1821,18 +2110,55 @@ const statusActive = "active";
       expect(spec!.rules[1].examples).toHaveLength(2);
 
       // 第一组
-      expect(spec!.rules[1].examples[0].title).toBe("Example");
-      expect(spec!.rules[1].examples[0].description).toBe("下面的明明规则说明");
+      expect(spec!.rules[1].examples[0].title).toBe("下面的明明规则说明");
+      expect(spec!.rules[1].examples[0].description).toBe("");
       expect(spec!.rules[1].examples[0].content).toHaveLength(2);
       expect(spec!.rules[1].examples[0].content[0].type).toBe("good");
       expect(spec!.rules[1].examples[0].content[1].type).toBe("bad");
 
       // 第二组
-      expect(spec!.rules[1].examples[1].title).toBe("Example");
-      expect(spec!.rules[1].examples[1].description).toBe("另一种场景");
+      expect(spec!.rules[1].examples[1].title).toBe("另一种场景");
+      expect(spec!.rules[1].examples[1].description).toBe("");
       expect(spec!.rules[1].examples[1].content).toHaveLength(2);
       expect(spec!.rules[1].examples[1].content[0].type).toBe("good");
       expect(spec!.rules[1].examples[1].content[1].type).toBe("bad");
     });
+
+    it("should parse Example with title and description paragraph", () => {
+      const mockContent = `# 基础代码规范 \`[JsTs.Base]\`
+
+## 函数行数限制 \`[JsTs.Base.FuncLines]\`
+
+- 函数不能太长
+
+### Example: 函数行数
+
+例子说明 desc
+
+#### Good: 函数不超过 200 行
+
+\`\`\`javascript
+function getUserInfo() {
+  // ... 小于等于 200
+}
+\`\`\`
+
+#### Bad: 函数超过 200 行
+
+\`\`\`javascript
+function getUserInfo() {
+  // ... 大于 200
+}
+\`\`\``;
+
+      const spec = service.parseSpecFile("js&ts.base.md", mockContent);
+      expect(spec).not.toBeNull();
+      expect(spec!.rules[1].examples).toHaveLength(1);
+      expect(spec!.rules[1].examples[0].title).toBe("函数行数");
+      expect(spec!.rules[1].examples[0].description).toBe("例子说明 desc");
+      expect(spec!.rules[1].examples[0].content).toHaveLength(2);
+      expect(spec!.rules[1].examples[0].content[0].type).toBe("good");
+      expect(spec!.rules[1].examples[0].content[0].title).toBe("函数不超过 200 行");
+    });
   });
 });

package/src/review-spec/review-spec.service.ts

@@ -694,13 +694,18 @@ export class ReviewSpecService {
       const trimmedGroup = groupSection.trim();
       if (!trimmedGroup) continue;
 
-      // 提取分组描述，如 "### Example: 命名规则说明"
+      // 提取分组标题和描述，如 "### Example: 函数行数"
       let exampleTitle = "";
       let exampleDescription = "";
       const groupMatch = trimmedGroup.match(/^###\s+Example\s*[:：]\s*(.+)/i);
       if (groupMatch) {
-        exampleTitle = "Example";
-        exampleDescription = groupMatch[1].trim();
+        exampleTitle = groupMatch[1].trim();
+        // 提取标题行和第一个 #### 之间的文本作为 description
+        const afterTitle = trimmedGroup.slice(trimmedGroup.indexOf("\n")).trim();
+        const firstSubIdx = afterTitle.search(/(?:^|\n)####\s+/);
+        if (firstSubIdx > 0) {
+          exampleDescription = afterTitle.slice(0, firstSubIdx).trim();
+        }
       }
 
       // 在分组内按 #### 提取 Good/Bad
@@ -794,12 +799,12 @@ export class ReviewSpecService {
     specs: ReviewSpec[],
     changedFiles?: ChangedFileCollection,
   ): T[] {
-    // 构建 spec filename -> includes 的映射
+    // 构建 rule.id -> includes 的映射（规则级优先，文件级兜底）
     const specIncludesMap = new Map<string, string[]>();
     for (const spec of specs) {
-      // 从规则 ID 前缀推断 spec filename
       for (const rule of spec.rules) {
-        specIncludesMap.set(rule.id, spec.includes);
+        // 规则级 includes 覆盖文件级 includes，与 severity 优先级一致
+        specIncludesMap.set(rule.id, rule.includes ?? spec.includes);
       }
     }