@spaceflow/review 0.78.0 → 0.79.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## [0.78.0](https://github.com/Lydanne/spaceflow/compare/@spaceflow/review@0.77.0...@spaceflow/review@0.78.0) (2026-04-07)
+
+### 新特性
+
+* **review:** 新增 code-* 代码结构过滤语法,支持按函数/类/接口等类型审查新增代码 ([f3b17d3](https://github.com/Lydanne/spaceflow/commit/f3b17d36c6360269a2fd4075311ae764e85cf428))
+
+### 代码重构
+
+* **ci:** 将 PR 审查工作流日志级别从 -vv 提升至 -vvv ([43bd563](https://github.com/Lydanne/spaceflow/commit/43bd5632dbd7151e11977520ca0634fdbc393279))
+* **review:** 优化 syncReactionsToIssues 中的 issue 匹配逻辑,优先使用 issue-key 精确匹配并回退到 path+position 匹配 ([eb8ea47](https://github.com/Lydanne/spaceflow/commit/eb8ea47c56466aa25d58358a09f1e0c9094aa28d))
+* **review:** 修改 buildLinesWithNumbers 忽略占位符格式,从 `...... ..| ignore X-Y code` 改为 `....... ignore X-Y line .......` ([a45dc1a](https://github.com/Lydanne/spaceflow/commit/a45dc1a5b92d50f75682782cec24b0100732e434))
+* **review:** 将 code-* 语法从 includes 迁移至独立 filterCodeBlocks 配置项 ([ed4b921](https://github.com/Lydanne/spaceflow/commit/ed4b9217a563d992b76d1e55af21f9b364329737))
+* **review:** 将 filterCodeBlocks 重命名为 whenModifiedCode,简化代码结构过滤语法 ([951c570](https://github.com/Lydanne/spaceflow/commit/951c570ceb7c04d25265d043c3948687bbb230f1))
+* **review:** 将 prompt 构建逻辑提取到独立的 prompt 模块,新增类型验证和 schema 定义 ([5f21356](https://github.com/Lydanne/spaceflow/commit/5f21356964ad4f08004e229ac7bd538c0301b37d))
+* **review:** 将 review-pr-comment-utils 重构为 utils/review-pr-comment,新增完整测试覆盖 ([29041b6](https://github.com/Lydanne/spaceflow/commit/29041b635e3a6ecbd2b2ae49ad1b657aa1a66e9c))
+* **review:** 将 skipDuplicateWorkflow 重构为 duplicateWorkflowResolved,支持 skip/delete 两种处理模式 ([37238f9](https://github.com/Lydanne/spaceflow/commit/37238f9ae8ed38c67f46acb963e3ebb795c0ef71))
+* **review:** 将无效 commit hash 的 issue 标记为 invalid 并清除 commit 字段,移除 code-* 前缀语法支持 ([0a89136](https://github.com/Lydanne/spaceflow/commit/0a89136b32cf49a70dbdfa26683e97ee13dc207e))
+* **review:** 提前检测无效 commit hash,在 fillIssueAuthors 中对已有 author 的 issue 也进行校验 ([c166496](https://github.com/Lydanne/spaceflow/commit/c1664966066bca032bd936b6c1d2c8f320949f9c))
+* **review:** 新增 systemRules 静态规则系统,支持 maxLinesPerFile 限制并跳过超限文件的 LLM 审查 ([3721d0f](https://github.com/Lydanne/spaceflow/commit/3721d0f46d40f71230aceb060350682a3d5642d7))
+* **review:** 新增 whenModifiedCode 过滤逻辑,跳过无匹配代码块的文件并记录日志 ([3d0c1e1](https://github.com/Lydanne/spaceflow/commit/3d0c1e1a4b492e62104af92d16208c206934ad10))
+* **review:** 简化 includes glob 模式,移除冗余的 `*/**` 前缀 ([56cf145](https://github.com/Lydanne/spaceflow/commit/56cf145fbf8f1311df9d538fffc61581d4ead400))
+
+### 测试用例
+
+* **review:** 新增全量 diff 语义测试,验证 added| 对分支首次引入文件的持续匹配行为 ([5b72577](https://github.com/Lydanne/spaceflow/commit/5b725772091d1d4fe5207af1b7d176e705bdb8d3))
+
+### 其他修改
+
+* **review-summary:** released version 0.46.0 [no ci] ([72fa783](https://github.com/Lydanne/spaceflow/commit/72fa783ef5c104d654a29481300d791b333df0ee))
+* **scripts:** released version 0.32.0 [no ci] ([7871aa9](https://github.com/Lydanne/spaceflow/commit/7871aa94a7f1227d6f09fc43ea69fb7d4e193ec4))
+* **shell:** released version 0.32.0 [no ci] ([88bdc81](https://github.com/Lydanne/spaceflow/commit/88bdc81cb0ec7809fbd76c7b157e0177b2f4db20))
+
 ## [0.77.0](https://github.com/Lydanne/spaceflow/compare/@spaceflow/review@0.76.0...@spaceflow/review@0.77.0) (2026-04-07)
 
 ### 新特性

package/dist/index.js

@@ -1,6 +1,6 @@
 import { LlmJsonPut, REVIEW_STATE, addLocaleResources, calculateNewLineNumber, createStreamLoggerState, defineExtension, logStreamEvent, normalizeVerbose, parallel, parseChangedLinesFromPatch, parseDiffText, parseHunksFromPatch, parseRepoUrl, parseVerbose, shouldLog, t, z } from "@spaceflow/core";
 import { access, mkdir, readFile, readdir, writeFile } from "fs/promises";
-import { basename, dirname, extname, isAbsolute, join, relative } from "path";
+import { basename, dirname, extname, isAbsolute, join, normalize, relative } from "path";
 import { homedir } from "os";
 import { execSync, spawn } from "child_process";
 import micromatch_0 from "micromatch";
@@ -3239,11 +3239,14 @@ class ReviewContextBuilder {
         if (reviewConf.references?.length) {
             specSources.push(...reviewConf.references);
         }
+        const normalizedFiles = this.normalizeFilePaths(options.files);
         // 解析本地模式：非 CI、非 PR、无 base/head 时默认启用 uncommitted 模式
+        // 当显式指定 files 时，强制走“按文件审查模式”，不进入本地未提交模式
         const localMode = this.resolveLocalMode(options, {
             ci: options.ci,
             hasPrNumber: !!prNumber,
-            hasBaseHead: !!(options.base || options.head)
+            hasBaseHead: !!(options.base || options.head),
+            hasFiles: !!normalizedFiles?.length
         });
         // 当没有 PR 且没有指定 base/head 且不是本地模式时，自动获取默认值
         let baseRef = options.base;
@@ -3273,7 +3276,7 @@ class ReviewContextBuilder {
             includes: ctxIncludes,
             whenModifiedCode: options.whenModifiedCode ?? reviewConf.whenModifiedCode,
             llmMode: options.llmMode ?? titleOptions.llmMode ?? reviewConf.llmMode,
-            files: this.normalizeFilePaths(options.files),
+            files: normalizedFiles,
             commits: options.commits,
             verifyFixes: options.verifyFixes ?? titleOptions.verifyFixes ?? reviewConf.verifyFixes ?? true,
             verifyConcurrency: options.verifyConcurrency ?? reviewConf.verifyFixesConcurrency ?? 10,
@@ -3303,6 +3306,10 @@ class ReviewContextBuilder {
    * - 显式指定 --no-local 时禁用
    * - 非 CI、非 PR、无 base/head 时默认启用 uncommitted 模式
    */ resolveLocalMode(options, env) {
+        // 显式指定了 files，优先进入按文件审查模式
+        if (env.hasFiles) {
+            return false;
+        }
         // 显式指定了 --no-local
         if (options.local === false) {
             return false;
@@ -3328,13 +3335,17 @@ class ReviewContextBuilder {
    */ normalizeFilePaths(files) {
         if (!files || files.length === 0) return files;
         const cwd = process.cwd();
-        return files.map((file)=>{
-            if (isAbsolute(file)) {
-                // 绝对路径转换为相对路径
-                return relative(cwd, file);
-            }
-            return file;
-        });
+        return files.map((file)=>this.normalizeSingleFilePath(file, cwd));
+    }
+    /**
+   * 规范化单个文件路径为仓库相对路径：
+   * - 绝对路径转相对路径
+   * - 统一分隔符为 /
+   * - 移除前导 ./
+   */ normalizeSingleFilePath(file, cwd) {
+        const normalizedInput = normalize(file);
+        const relativePath = isAbsolute(normalizedInput) ? relative(cwd, normalizedInput) : normalizedInput;
+        return relativePath.replaceAll("\\", "/").replace(/^\.\/+/, "");
     }
     /**
    * 根据 AnalyzeDeletionsMode 和当前环境解析是否启用删除代码分析
@@ -5147,6 +5158,10 @@ class ReviewService {
         const source = await this.resolveSourceData(context);
         if (source.earlyReturn) return source.earlyReturn;
         const { prModel, commits, changedFiles, headSha, isDirectFileMode } = source;
+        const effectiveWhenModifiedCode = isDirectFileMode ? undefined : context.whenModifiedCode;
+        if (isDirectFileMode && context.whenModifiedCode?.length && shouldLog(verbose, 1)) {
+            console.log(`ℹ️  直接文件模式下忽略 whenModifiedCode 过滤`);
+        }
         // 2. 规则匹配
         const specs = await this.issueFilter.loadSpecs(specSources, verbose);
         const applicableSpecs = this.reviewSpecService.filterApplicableSpecs(specs, changedFiles);
@@ -5174,7 +5189,7 @@ class ReviewService {
         if (shouldLog(verbose, 1)) {
             console.log(`🔄 当前审查轮次: ${(existingResultModel?.round ?? 0) + 1}`);
         }
-        const reviewPrompt = await this.buildReviewPrompt(specs, changedFiles, fileContents, commits, existingResultModel?.result ?? null, context.whenModifiedCode, verbose, context.systemRules);
+        const reviewPrompt = await this.buildReviewPrompt(specs, changedFiles, fileContents, commits, existingResultModel?.result ?? null, effectiveWhenModifiedCode, verbose, context.systemRules);
         const result = await this.runLLMReview(llmMode, reviewPrompt, {
             verbose,
             concurrency: context.concurrency,
@@ -5230,7 +5245,7 @@ class ReviewService {
    * 如果需要提前返回（如同分支、重复 workflow），通过 earlyReturn 字段传递。
    */ async resolveSourceData(context) {
         const { owner, repo, prNumber, baseRef, headRef, verbose, ci, includes, files, commits: filterCommits, localMode, duplicateWorkflowResolved } = context;
-        const isDirectFileMode = !!(files && files.length > 0 && baseRef === headRef);
+        const isDirectFileMode = !!(files && files.length > 0 && !prNumber);
         let isLocalMode = !!localMode;
         let effectiveBaseRef = baseRef;
         let effectiveHeadRef = headRef;
@@ -5289,8 +5304,17 @@ class ReviewService {
                 }
             }
         }
-        // PR 模式、分支比较模式、或本地模式回退后的分支比较
-        if (prNumber) {
+        // 直接文件审查模式（-f）：绕过 diff，直接按指定文件构造审查输入
+        if (isDirectFileMode) {
+            if (shouldLog(verbose, 1)) {
+                console.log(`📥 直接审查指定文件模式 (${files.length} 个文件)`);
+            }
+            changedFiles = files.map((f)=>({
+                    filename: f,
+                    status: "modified"
+                }));
+            isLocalMode = true;
+        } else if (prNumber) {
             if (shouldLog(verbose, 1)) {
                 console.log(`📥 获取 PR #${prNumber} 信息 (owner: ${owner}, repo: ${repo})`);
             }
@@ -5319,15 +5343,7 @@ class ReviewService {
                 }
             }
         } else if (effectiveBaseRef && effectiveHeadRef) {
-            if (files && files.length > 0 && effectiveBaseRef === effectiveHeadRef) {
-                if (shouldLog(verbose, 1)) {
-                    console.log(`📥 直接审查指定文件模式 (${files.length} 个文件)`);
-                }
-                changedFiles = files.map((f)=>({
-                        filename: f,
-                        status: "modified"
-                    }));
-            } else if (changedFiles.length === 0) {
+            if (changedFiles.length === 0) {
                 if (shouldLog(verbose, 1)) {
                     console.log(`📥 获取 ${effectiveBaseRef}...${effectiveHeadRef} 的差异 (owner: ${owner}, repo: ${repo})`);
                 }

package/package.json

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

package/src/review-context.ts

@@ -15,7 +15,7 @@ import { parseTitleOptions } from "./parse-title-options";
 import { type ReviewIssue, type UserInfo } from "./review-spec";
 import { readFile } from "fs/promises";
 import { join } from "path";
-import { isAbsolute, relative } from "path";
+import { isAbsolute, normalize, relative } from "path";
 import { homedir } from "os";
 import type { ReportFormat } from "./review-report";
 
@@ -137,11 +137,15 @@ export class ReviewContextBuilder {
       specSources.push(...reviewConf.references);
     }
 
+    const normalizedFiles = this.normalizeFilePaths(options.files);
+
     // 解析本地模式：非 CI、非 PR、无 base/head 时默认启用 uncommitted 模式
+    // 当显式指定 files 时，强制走“按文件审查模式”，不进入本地未提交模式
     const localMode = this.resolveLocalMode(options, {
       ci: options.ci,
       hasPrNumber: !!prNumber,
       hasBaseHead: !!(options.base || options.head),
+      hasFiles: !!normalizedFiles?.length,
     });
 
     // 当没有 PR 且没有指定 base/head 且不是本地模式时，自动获取默认值
@@ -175,7 +179,7 @@ export class ReviewContextBuilder {
       includes: ctxIncludes,
       whenModifiedCode: options.whenModifiedCode ?? reviewConf.whenModifiedCode,
       llmMode: options.llmMode ?? titleOptions.llmMode ?? reviewConf.llmMode,
-      files: this.normalizeFilePaths(options.files),
+      files: normalizedFiles,
       commits: options.commits,
       verifyFixes:
         options.verifyFixes ?? titleOptions.verifyFixes ?? reviewConf.verifyFixes ?? true,
@@ -219,8 +223,12 @@ export class ReviewContextBuilder {
    */
   resolveLocalMode(
     options: ReviewOptions,
-    env: { ci: boolean; hasPrNumber: boolean; hasBaseHead: boolean },
+    env: { ci: boolean; hasPrNumber: boolean; hasBaseHead: boolean; hasFiles: boolean },
   ): "uncommitted" | "staged" | false {
+    // 显式指定了 files，优先进入按文件审查模式
+    if (env.hasFiles) {
+      return false;
+    }
     // 显式指定了 --no-local
     if (options.local === false) {
       return false;
@@ -249,13 +257,19 @@ export class ReviewContextBuilder {
     if (!files || files.length === 0) return files;
 
     const cwd = process.cwd();
-    return files.map((file) => {
-      if (isAbsolute(file)) {
-        // 绝对路径转换为相对路径
-        return relative(cwd, file);
-      }
-      return file;
-    });
+    return files.map((file) => this.normalizeSingleFilePath(file, cwd));
+  }
+
+  /**
+   * 规范化单个文件路径为仓库相对路径：
+   * - 绝对路径转相对路径
+   * - 统一分隔符为 /
+   * - 移除前导 ./
+   */
+  private normalizeSingleFilePath(file: string, cwd: string): string {
+    const normalizedInput = normalize(file);
+    const relativePath = isAbsolute(normalizedInput) ? relative(cwd, normalizedInput) : normalizedInput;
+    return relativePath.replaceAll("\\", "/").replace(/^\.\/+/, "");
   }
 
   /**

package/src/review.service.spec.ts

@@ -127,6 +127,10 @@ describe("ReviewService", () => {
       parseDiffText: vi.fn().mockReturnValue([]),
       getRemoteUrl: vi.fn().mockReturnValue(null),
       parseRepositoryFromRemoteUrl: vi.fn().mockReturnValue(null),
+      getUncommittedFiles: vi.fn().mockReturnValue([]),
+      getStagedFiles: vi.fn().mockReturnValue([]),
+      getUncommittedDiff: vi.fn().mockReturnValue([]),
+      getStagedDiff: vi.fn().mockReturnValue([]),
       getChangedFilesBetweenRefs: vi.fn().mockResolvedValue([]),
       getCommitsBetweenRefs: vi.fn().mockResolvedValue([]),
       getDiffBetweenRefs: vi.fn().mockResolvedValue([]),
@@ -419,6 +423,26 @@ describe("ReviewService", () => {
       expect(result.success).toBe(true);
     });
 
+    it("should ignore whenModifiedCode in direct file mode", async () => {
+      const context: ReviewContext = {
+        owner: "owner",
+        repo: "repo",
+        files: ["src/app.ts"],
+        specSources: ["/spec/dir"],
+        dryRun: true,
+        ci: false,
+        llmMode: "openai",
+        whenModifiedCode: ["function", "class"],
+      };
+      const buildReviewPromptSpy = vi.spyOn(service as any, "buildReviewPrompt");
+
+      const result = await service.execute(context);
+
+      expect(result.success).toBe(true);
+      expect(buildReviewPromptSpy).toHaveBeenCalled();
+      expect(buildReviewPromptSpy.mock.calls[0][5]).toBeUndefined();
+    });
+
     it("should filter files by includes pattern", async () => {
       const context: ReviewContext = {
         owner: "owner",
@@ -1363,14 +1387,28 @@ describe("ReviewService", () => {
 
     it("should normalize absolute file paths", async () => {
       configService.get.mockReturnValue({ repository: "owner/repo", refName: "main" });
+      const absPath = `${process.cwd()}/src/file.ts`;
       const options = {
         dryRun: false,
         ci: false,
-        files: ["/absolute/path/to/file.ts", "relative.ts"],
+        files: [absPath, "./relative.ts"],
       };
       const context = await service.getContextFromEnv(options as any);
       expect(context.files).toBeDefined();
-      expect(context.files![1]).toBe("relative.ts");
+      expect(context.files).toEqual(["src/file.ts", "relative.ts"]);
+    });
+
+    it("should force direct file mode when files are specified", async () => {
+      configService.get.mockReturnValue({ repository: "owner/repo", refName: "main" });
+      const options = {
+        dryRun: false,
+        ci: false,
+        local: "uncommitted" as const,
+        files: ["./miniprogram/utils/asyncSharedUtilsLoader.js"],
+      };
+      const context = await service.getContextFromEnv(options as any);
+      expect(context.localMode).toBe(false);
+      expect(context.files).toEqual(["miniprogram/utils/asyncSharedUtilsLoader.js"]);
     });
 
     it("should auto-detect base/head with verbose logging", async () => {
@@ -1429,6 +1467,30 @@ describe("ReviewService", () => {
     });
   });
 
+  describe("ReviewService.resolveSourceData - direct file mode", () => {
+    it("should bypass local uncommitted scanning when files are specified", async () => {
+      const context: ReviewContext = {
+        owner: "o",
+        repo: "r",
+        dryRun: true,
+        ci: false,
+        specSources: ["/spec"],
+        files: ["miniprogram/utils/asyncSharedUtilsLoader.js"],
+        localMode: false,
+      };
+
+      const result = await (service as any).resolveSourceData(context);
+
+      expect(result.isDirectFileMode).toBe(true);
+      expect(result.isLocalMode).toBe(true);
+      expect(result.changedFiles).toEqual([
+        { filename: "miniprogram/utils/asyncSharedUtilsLoader.js", status: "modified" },
+      ]);
+      expect(mockGitSdkService.getUncommittedFiles).not.toHaveBeenCalled();
+      expect(mockGitSdkService.getStagedFiles).not.toHaveBeenCalled();
+    });
+  });
+
   describe("ReviewService.getFilesForCommit", () => {
     it("should return files from git sdk", async () => {
       mockGitSdkService.getFilesForCommit.mockResolvedValue([

package/src/review.service.ts

@@ -97,6 +97,10 @@ export class ReviewService {
     if (source.earlyReturn) return source.earlyReturn;
 
     const { prModel, commits, changedFiles, headSha, isDirectFileMode } = source;
+    const effectiveWhenModifiedCode = isDirectFileMode ? undefined : context.whenModifiedCode;
+    if (isDirectFileMode && context.whenModifiedCode?.length && shouldLog(verbose, 1)) {
+      console.log(`ℹ️  直接文件模式下忽略 whenModifiedCode 过滤`);
+    }
 
     // 2. 规则匹配
     const specs = await this.issueFilter.loadSpecs(specSources, verbose);
@@ -147,7 +151,7 @@ export class ReviewService {
       fileContents,
       commits,
       existingResultModel?.result ?? null,
-      context.whenModifiedCode,
+      effectiveWhenModifiedCode,
       verbose,
       context.systemRules,
     );
@@ -234,7 +238,7 @@ export class ReviewService {
       duplicateWorkflowResolved,
     } = context;
 
-    const isDirectFileMode = !!(files && files.length > 0 && baseRef === headRef);
+    const isDirectFileMode = !!(files && files.length > 0 && !prNumber);
     let isLocalMode = !!localMode;
     let effectiveBaseRef = baseRef;
     let effectiveHeadRef = headRef;
@@ -294,8 +298,16 @@ export class ReviewService {
       }
     }
 
+    // 直接文件审查模式（-f）：绕过 diff，直接按指定文件构造审查输入
+    if (isDirectFileMode) {
+      if (shouldLog(verbose, 1)) {
+        console.log(`📥 直接审查指定文件模式 (${files!.length} 个文件)`);
+      }
+      changedFiles = files!.map((f) => ({ filename: f, status: "modified" as const }));
+      isLocalMode = true;
+    }
     // PR 模式、分支比较模式、或本地模式回退后的分支比较
-    if (prNumber) {
+    else if (prNumber) {
       if (shouldLog(verbose, 1)) {
         console.log(`📥 获取 PR #${prNumber} 信息 (owner: ${owner}, repo: ${repo})`);
       }
@@ -330,12 +342,7 @@ export class ReviewService {
         }
       }
     } else if (effectiveBaseRef && effectiveHeadRef) {
-      if (files && files.length > 0 && effectiveBaseRef === effectiveHeadRef) {
-        if (shouldLog(verbose, 1)) {
-          console.log(`📥 直接审查指定文件模式 (${files.length} 个文件)`);
-        }
-        changedFiles = files.map((f) => ({ filename: f, status: "modified" as const }));
-      } else if (changedFiles.length === 0) {
+      if (changedFiles.length === 0) {
         if (shouldLog(verbose, 1)) {
           console.log(
             `📥 获取 ${effectiveBaseRef}...${effectiveHeadRef} 的差异 (owner: ${owner}, repo: ${repo})`,