@spaceflow/review 0.82.0 → 1.0.0

package/package.json

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

package/src/changed-file-collection.ts

@@ -59,6 +59,17 @@ export class ChangedFileCollection implements Iterable<ChangedFile> {
     return this._files.map(fn);
   }
 
+  /**
+   * 获取指定文件的变更状态
+   */
+  getStatus(filename: string): string | undefined {
+    if (!filename) return undefined;
+    for (const f of this._files) {
+      if (f.filename === filename) return f.status;
+    }
+    return undefined;
+  }
+
   countByStatus(): FileStatusCount {
     let added = 0,
       modified = 0,

package/src/mcp/index.ts

@@ -2,7 +2,7 @@ import { t, z, type SpaceflowContext, type GitProviderService } from "@spaceflow
 import { ReviewSpecService } from "../review-spec";
 import { ChangedFileCollection } from "../changed-file-collection";
 import type { ReviewConfig } from "../review.config";
-import { extractGlobsFromIncludes } from "../review-includes-filter";
+import { matchIncludes } from "../review-includes-filter";
 import { join } from "path";
 import { existsSync } from "fs";
 
@@ -115,16 +115,11 @@ export const tools = [
         allSpecs,
         ChangedFileCollection.from([{ filename: filePath }]),
       );
-      const micromatchModule = await import("micromatch");
-      const micromatch = micromatchModule.default || micromatchModule;
       const rules = applicableSpecs.flatMap((spec) =>
         spec.rules
           .filter((rule) => {
             const includes = rule.includes || spec.includes;
-            if (includes.length === 0) return true;
-            const globs = extractGlobsFromIncludes(includes);
-            if (globs.length === 0) return true;
-            return micromatch.isMatch(filePath, globs, { matchBase: true });
+            return matchIncludes(includes, filePath);
           })
           .map((rule) => ({
             id: rule.id,
@@ -135,9 +130,13 @@ export const tools = [
             ...(includeExamples && rule.examples.length > 0
               ? {
                   examples: rule.examples.map((ex) => ({
-                    type: ex.type,
-                    lang: ex.lang,
-                    code: ex.code,
+                    title: ex.title,
+                    description: ex.description,
+                    content: ex.content.map((c) => ({
+                      title: c.title,
+                      type: c.type,
+                      description: c.description,
+                    })),
                   })),
                 }
               : {}),
@@ -170,9 +169,13 @@ export const tools = [
         includes: spec.includes,
         overrides: rule.overrides,
         examples: rule.examples.map((ex) => ({
-          type: ex.type,
-          lang: ex.lang,
-          code: ex.code,
+          title: ex.title,
+          description: ex.description,
+          content: ex.content.map((c) => ({
+            title: c.title,
+            type: c.type,
+            description: c.description,
+          })),
         })),
       };
     },
@@ -209,9 +212,13 @@ export const tools = [
           ...(includeExamples && rule.examples.length > 0
             ? {
                 examples: rule.examples.map((ex) => ({
-                  type: ex.type,
-                  lang: ex.lang,
-                  code: ex.code,
+                  title: ex.title,
+                  description: ex.description,
+                  content: ex.content.map((c) => ({
+                    title: c.title,
+                    type: c.type,
+                    description: c.description,
+                  })),
                 })),
               }
             : { hasExamples: rule.examples.length > 0 }),

package/src/prompt/specs-section.ts

@@ -0,0 +1,47 @@
+import type { ReviewSpec, RuleExample, RuleContent } from "../review-spec/types";
+
+/**
+ * 构建 specs 的 prompt 部分
+ */
+export function buildSpecsSection(specs: ReviewSpec[]): string {
+  return specs
+    .map((spec) => {
+      const firstRule = spec.rules[0];
+      const rulesText = spec.rules
+        .slice(1)
+        .map((rule) => {
+          let text = `#### [${rule.id}] ${rule.title}\n`;
+          if (rule.description) {
+            text += `${rule.description}\n`;
+          }
+          if (rule.examples.length > 0) {
+            for (const example of rule.examples) {
+              text += formatExample(example);
+            }
+          }
+          return text;
+        })
+        .join("\n");
+
+      return `### ${firstRule.title}\n- 规范文件: ${spec.filename}\n- 适用扩展名: ${spec.extensions.join(", ")}\n\n${rulesText}`;
+    })
+    .join("\n\n-------------------\n\n");
+}
+
+function formatExample(example: RuleExample): string {
+  let text = "";
+  if (example.title) {
+    text += `##### ${example.title}\n`;
+  }
+  if (example.description) {
+    text += `${example.description}\n`;
+  }
+  for (const item of example.content) {
+    text += formatContent(item);
+  }
+  return text;
+}
+
+function formatContent(item: RuleContent): string {
+  return `###### ${item.type}${item.title ? `: ${item.title}` : ""}\n${item.description}\n`;
+}

package/src/review-includes-filter.spec.ts

@@ -4,6 +4,7 @@ import {
   filterFilesByIncludes,
   extractGlobsFromIncludes,
   extractCodeBlockTypes,
+  matchIncludes,
 } from "./review-includes-filter";
 
 describe("review-includes-filter", () => {
@@ -281,4 +282,86 @@ describe("review-includes-filter", () => {
       expect(extractCodeBlockTypes([])).toEqual([]);
     });
   });
+
+  describe("matchIncludes", () => {
+    const glob = "**/*.ts";
+
+    it("includes 为空时返回 true", () => {
+      expect(matchIncludes([], "src/foo.ts")).toBe(true);
+    });
+
+    it("filename 为空时返回 false", () => {
+      expect(matchIncludes([glob], "")).toBe(false);
+    });
+
+    it("不传 fileStatus 时降级为纯 glob 匹配", () => {
+      expect(matchIncludes([glob], "src/foo.ts")).toBe(true);
+      expect(matchIncludes([glob], "src/foo.vue")).toBe(false);
+    });
+
+    it("不传 fileStatus 时 status 前缀降级为纯 glob 匹配", () => {
+      // added|**/*.ts 在无 status 信息时，降级为 glob **/*.ts 匹配
+      expect(matchIncludes([`added|${glob}`], "src/foo.ts")).toBe(true);
+      expect(matchIncludes([`added|${glob}`], "src/foo.vue")).toBe(false);
+    });
+
+    it("无前缀 glob 不限 status，匹配所有符合的文件", () => {
+      expect(matchIncludes([glob], "src/foo.ts", "added")).toBe(true);
+      expect(matchIncludes([glob], "src/foo.ts", "modified")).toBe(true);
+      expect(matchIncludes([glob], "src/foo.ts", "removed")).toBe(true);
+    });
+
+    it("added| 前缀只匹配 added 状态文件", () => {
+      expect(matchIncludes([`added|${glob}`], "src/foo.ts", "added")).toBe(true);
+      expect(matchIncludes([`added|${glob}`], "src/foo.ts", "modified")).toBe(false);
+    });
+
+    it("modified| 前缀只匹配 modified 状态文件", () => {
+      expect(matchIncludes([`modified|${glob}`], "src/foo.ts", "modified")).toBe(true);
+      expect(matchIncludes([`modified|${glob}`], "src/foo.ts", "added")).toBe(false);
+    });
+
+    it("deleted| 前缀匹配 removed 和 deleted 状态文件", () => {
+      expect(matchIncludes([`deleted|${glob}`], "src/old.ts", "removed")).toBe(true);
+      expect(matchIncludes([`deleted|${glob}`], "src/old.ts", "deleted")).toBe(true);
+      expect(matchIncludes([`deleted|${glob}`], "src/old.ts", "modified")).toBe(false);
+    });
+
+    it("排除模式 ! 优先过滤", () => {
+      expect(matchIncludes([glob, "!**/*.spec.ts"], "src/foo.spec.ts", "added")).toBe(false);
+      expect(matchIncludes([glob, "!**/*.spec.ts"], "src/foo.ts", "added")).toBe(true);
+    });
+
+    it("多个 status 前缀之间是 OR 关系", () => {
+      expect(matchIncludes([`added|${glob}`, `modified|${glob}`], "src/foo.ts", "added")).toBe(
+        true,
+      );
+      expect(matchIncludes([`added|${glob}`, `modified|${glob}`], "src/foo.ts", "modified")).toBe(
+        true,
+      );
+    });
+
+    it("无前缀 glob 与 status 前缀混用时任一命中即保留", () => {
+      expect(matchIncludes([glob, "added|**/*.vue"], "src/foo.ts", "modified")).toBe(true);
+      expect(matchIncludes([glob, "added|**/*.vue"], "src/foo.vue", "added")).toBe(true);
+      expect(matchIncludes([glob, "added|**/*.vue"], "src/foo.vue", "modified")).toBe(false);
+    });
+
+    it("status 内排除语法 added|!**/*.spec.ts", () => {
+      expect(matchIncludes([`added|${glob}`, "added|!**/*.spec.ts"], "src/foo.ts", "added")).toBe(
+        true,
+      );
+      expect(
+        matchIncludes([`added|${glob}`, "added|!**/*.spec.ts"], "src/foo.spec.ts", "added"),
+      ).toBe(false);
+    });
+
+    it("fileStatus 为 undefined 时走降级路径（纯 glob 匹配）", () => {
+      // matchIncludes 中 undefined 表示无 status 信息，降级为纯 glob 匹配
+      // 这与 filterFilesByIncludes 中 status=undefined fallback 为 modified 不同
+      // 因为 matchIncludes 用于 spec includes 场景，无 status 时应宽松匹配
+      expect(matchIncludes([`modified|${glob}`], "src/foo.ts")).toBe(true);
+      expect(matchIncludes([`added|${glob}`], "src/foo.ts")).toBe(true);
+    });
+  });
 });

package/src/review-includes-filter.ts

@@ -180,6 +180,86 @@ export function extractGlobsFromIncludes(includes: string[]): string[] {
   return includes.map((p) => parseIncludePattern(p).glob).filter((g) => g.length > 0);
 }
 
+/**
+ * 检查单个文件是否匹配 includes 模式列表，支持 `status|glob` 前缀语法。
+ *
+ * - 当 `fileStatus` 未提供时，status 前缀的 includes 降级为纯 glob 匹配（向后兼容）
+ * - 当 `fileStatus` 提供时，完整支持 `added|`/`modified|`/`deleted|` 前缀语义
+ *
+ * 算法与 `filterFilesByIncludes` 一致，但针对单文件场景优化：
+ * 1. 排除模式(`!`) 优先过滤
+ * 2. 无前缀正向 glob 匹配
+ * 3. 有 status 前缀的 glob 按文件实际 status 过滤
+ *
+ * @param includes    include 模式列表
+ * @param filename    待匹配的文件名
+ * @param fileStatus  文件变更状态（如 "added"/"modified"/"removed"），不提供时降级为纯 glob
+ * @returns           是否匹配
+ */
+export function matchIncludes(includes: string[], filename: string, fileStatus?: string): boolean {
+  if (!includes || includes.length === 0) return true;
+  if (!filename) return false;
+
+  const parsed = includes.map(parseIncludePattern);
+
+  // 无 status 信息时降级为纯 glob 匹配（向后兼容）
+  if (!fileStatus) {
+    const globs = extractGlobsFromIncludes(includes);
+    if (globs.length === 0) return true;
+    return micromatch.isMatch(filename, globs, { matchBase: true });
+  }
+
+  const normalizedStatus = STATUS_ALIAS[fileStatus.toLowerCase()] ?? "modified";
+
+  // 排除模式（以 ! 开头），用于最终全局过滤
+  const negativeGlobs = parsed
+    .filter((p) => p.status === undefined && p.glob.startsWith("!"))
+    .map((p) => p.glob.slice(1));
+  // 无前缀的正向 globs
+  const plainGlobs = parsed
+    .filter((p) => p.status === undefined && !p.glob.startsWith("!"))
+    .map((p) => p.glob);
+  // 有 status 前缀的 patterns
+  const statusPatterns = parsed.filter((p) => p.status !== undefined);
+
+  // 最终排除：命中排除模式的文件直接过滤掉
+  if (
+    negativeGlobs.length > 0 &&
+    micromatch.isMatch(filename, negativeGlobs, { matchBase: true })
+  ) {
+    return false;
+  }
+
+  // 正向匹配：无前缀 glob
+  if (plainGlobs.length > 0 && micromatch.isMatch(filename, plainGlobs, { matchBase: true })) {
+    return true;
+  }
+
+  // 正向匹配：有 status 前缀的 glob，按文件实际 status 过滤
+  if (statusPatterns.length > 0) {
+    const matchingStatusGlobs = statusPatterns
+      .filter(({ status }) => status === normalizedStatus)
+      .map(({ glob }) => glob);
+    if (matchingStatusGlobs.length > 0) {
+      const positiveGlobs = matchingStatusGlobs.filter((g) => !g.startsWith("!"));
+      const negativeStatusGlobs = matchingStatusGlobs
+        .filter((g) => g.startsWith("!"))
+        .map((g) => g.slice(1));
+      if (positiveGlobs.length > 0) {
+        const matchesPositive = micromatch.isMatch(filename, positiveGlobs, { matchBase: true });
+        const matchesNegative =
+          negativeStatusGlobs.length > 0 &&
+          micromatch.isMatch(filename, negativeStatusGlobs, { matchBase: true });
+        if (matchesPositive && !matchesNegative) {
+          return true;
+        }
+      }
+    }
+  }
+
+  return false;
+}
+
 /**
  * 从 whenModifiedCode 配置中解析代码结构过滤类型。
  * 只接受简单的类型名称，如 "function"、"class"、"interface"、"type"、"method"

package/src/review-issue-filter.spec.ts

@@ -86,6 +86,7 @@ describe("ReviewIssueFilter", () => {
       getCommitsBetweenRefs: vi.fn().mockResolvedValue([]),
       getDiffBetweenRefs: vi.fn().mockResolvedValue([]),
       getFileContent: vi.fn().mockResolvedValue(""),
+      getFileBlame: vi.fn().mockResolvedValue(new Map()),
       getFilesForCommit: vi.fn().mockResolvedValue([]),
       getWorkingFileContent: vi.fn().mockReturnValue(""),
       getCommitDiff: vi.fn().mockReturnValue([]),
@@ -264,6 +265,7 @@ describe("ReviewIssueFilter", () => {
         "abc",
         1,
         false,
+        undefined,
         3,
       );
       expect(result.has("test.ts")).toBe(true);
@@ -279,6 +281,56 @@ describe("ReviewIssueFilter", () => {
       expect(lines![0][0]).toBe("abc1234");
       expect(lines![1][0]).toBe("abc1234");
     });
+
+    it("should mask merge commit line hash when showAll is false", async () => {
+      gitProvider.getFileContent.mockResolvedValue("line1\nnew line");
+      mockGitSdkService.getFileBlame.mockResolvedValue(new Map([[2, "merge12"]]));
+      const changedFiles = [
+        { filename: "test.ts", status: "modified", patch: "@@ -1,1 +1,2 @@\n line1\n+new line" },
+      ];
+      const commits = [{ sha: "abc1234567890", commit: { message: "feat: add line" } }];
+
+      const result = await resolver.getFileContents(
+        "o",
+        "r",
+        changedFiles,
+        commits,
+        "abc",
+        1,
+        false,
+        false,
+        undefined,
+      );
+
+      const lines = result.get("test.ts");
+      expect(lines).toBeDefined();
+      expect(lines![1][0]).toBe("-------");
+    });
+
+    it("should keep merge commit line hash when showAll is true", async () => {
+      gitProvider.getFileContent.mockResolvedValue("line1\nnew line");
+      mockGitSdkService.getFileBlame.mockResolvedValue(new Map([[2, "merge12"]]));
+      const changedFiles = [
+        { filename: "test.ts", status: "modified", patch: "@@ -1,1 +1,2 @@\n line1\n+new line" },
+      ];
+      const commits = [{ sha: "abc1234567890", commit: { message: "feat: add line" } }];
+
+      const result = await resolver.getFileContents(
+        "o",
+        "r",
+        changedFiles,
+        commits,
+        "abc",
+        1,
+        false,
+        true,
+        undefined,
+      );
+
+      const lines = result.get("test.ts");
+      expect(lines).toBeDefined();
+      expect(lines![1][0]).toBe("merge12");
+    });
   });
 
   describe("getChangedFilesBetweenRefs", () => {

package/src/review-llm.ts

@@ -19,11 +19,10 @@ import {
 } from "./review-spec";
 import { readdir } from "fs/promises";
 import { dirname, extname } from "path";
-import micromatch from "micromatch";
 import type { FileReviewPrompt, ReviewPrompt, LLMReviewOptions } from "./types/review-llm";
 import { buildLinesWithNumbers, buildCommitsSection, extractCodeBlocks } from "./utils/review-llm";
 import { ChangedFileCollection } from "./changed-file-collection";
-import { extractCodeBlockTypes, extractGlobsFromIncludes } from "./review-includes-filter";
+import { matchIncludes, extractCodeBlockTypes } from "./review-includes-filter";
 import {
   REVIEW_SCHEMA,
   buildFileReviewPrompt,
@@ -63,8 +62,9 @@ export class ReviewLlmProcessor {
    * 根据文件过滤 specs，只返回与该文件匹配的规则
    * - 如果 spec 有 includes 配置，只有当文件名匹配 includes 模式时才包含该 spec
    * - 如果 spec 没有 includes 配置，则按扩展名匹配
+   * - 支持 `added|`/`modified|`/`deleted|` 前缀语法，需传入 fileStatus
    */
-  filterSpecsForFile(specs: ReviewSpec[], filename: string): ReviewSpec[] {
+  filterSpecsForFile(specs: ReviewSpec[], filename: string, fileStatus?: string): ReviewSpec[] {
     const ext = extname(filename).slice(1).toLowerCase();
     if (!ext) return [];
 
@@ -75,11 +75,9 @@ export class ReviewLlmProcessor {
       }
 
       // 如果有 includes 配置，检查文件名是否匹配 includes 模式
-      // 需先提取纯 glob（去掉 added|/modified| 前缀，过滤 code-* 空串），避免 micromatch 报错
+      // 使用 matchIncludes 支持 status|glob 前缀语法
       if (spec.includes.length > 0) {
-        const globs = extractGlobsFromIncludes(spec.includes);
-        if (globs.length === 0) return true;
-        return micromatch.isMatch(filename, globs, { matchBase: true });
+        return matchIncludes(spec.includes, filename, fileStatus);
       }
 
       // 没有 includes 配置，扩展名匹配即可
@@ -124,7 +122,7 @@ export class ReviewLlmProcessor {
           const fileDirectoryInfo = await this.getFileDirectoryInfo(filename);
 
           // 根据文件过滤 specs，只注入与当前文件匹配的规则
-          const fileSpecs = this.filterSpecsForFile(specs, filename);
+          const fileSpecs = this.filterSpecsForFile(specs, filename, file.status);
 
           // 从全局 whenModifiedCode 配置中解析代码结构过滤类型
           const codeBlockTypes = whenModifiedCode ? extractCodeBlockTypes(whenModifiedCode) : [];

package/src/review-source-resolver.ts

@@ -150,6 +150,7 @@ export class ReviewSourceResolver {
       headSha,
       context.prNumber,
       isLocalMode,
+      context.showAll,
       context.verbose,
     );
     return {
@@ -313,19 +314,30 @@ export class ReviewSourceResolver {
     rawChangedFiles: ChangedFile[],
     isDirectFileMode: boolean,
   ): Promise<CommitsAndFiles> {
-    const { owner, repo, prNumber, verbose, includes, files, commits: filterCommits } = context;
+    const {
+      owner,
+      repo,
+      prNumber,
+      verbose,
+      includes,
+      files,
+      commits: filterCommits,
+      showAll,
+    } = context;
     let changedFiles = ChangedFileCollection.from(rawChangedFiles);
 
-    // 0. 过滤掉 merge commit
-    {
+    // 0. 过滤掉 merge commit（showAll=false 时启用）
+    if (!showAll) {
       const before = commits.length;
       commits = commits.filter((c) => {
         const message = c.commit?.message || "";
-        return !message.startsWith("Merge ");
+        return !/^merge\b/i.test(message);
       });
       if (before !== commits.length && shouldLog(verbose, 1)) {
         console.log(`   跳过 Merge Commits: ${before} -> ${commits.length} 个`);
       }
+    } else if (shouldLog(verbose, 2)) {
+      console.log(`   showAll=true，跳过 Merge Commit 过滤`);
     }
 
     // 1. 按指定的 files 过滤
@@ -426,10 +438,13 @@ export class ReviewSourceResolver {
     ref: string,
     prNumber?: number,
     isLocalMode?: boolean,
+    showAll?: boolean,
     verbose?: VerboseLevel,
   ): Promise<FileContentsMap> {
     const contents: FileContentsMap = new Map();
     const latestCommitHash = commits[commits.length - 1]?.sha?.slice(0, 7) || "+local+";
+    const validCommitHashes = new Set(commits.map((c) => c.sha?.slice(0, 7)).filter(Boolean));
+    const shouldMaskUnknownChangedLines = !showAll && validCommitHashes.size > 0;
 
     if (shouldLog(verbose, 1)) {
       console.log(`📊 正在构建行号到变更的映射...`);
@@ -503,6 +518,9 @@ export class ReviewSourceResolver {
               return ["-------", line];
             }
             const hash = blameMap?.get(lineNum) ?? latestCommitHash;
+            if (shouldMaskUnknownChangedLines && !validCommitHashes.has(hash)) {
+              return ["-------", line];
+            }
             return [hash, line];
           });
           contents.set(file.filename, contentLines);