@spaceflow/review 0.77.0 → 0.78.0

package/src/prompt/pr-description.ts

@@ -0,0 +1,149 @@
+import type { PromptFn } from "./types";
+import { validateArray } from "./types";
+import type { PullRequestCommit, ChangedFile } from "@spaceflow/core";
+import type { FileContentsMap } from "../review-spec";
+
+/**
+ * 内存使用限制常量
+ */
+const MEMORY_LIMITS = {
+  MAX_TOTAL_LENGTH: 8000, // 代码变更内容最大总长度
+  MAX_FILES: 30, // 最大文件数量
+  MAX_SNIPPET_LENGTH: 50, // 每个文件最大代码行数
+  MAX_COMMITS: 10, // 最大 commit 数量（用于标题生成）
+  MAX_FILES_FOR_TITLE: 20, // 标题生成时最大文件数量
+} as const;
+
+/**
+ * PR 描述生成提示词
+ */
+export interface PrDescriptionContext {
+  commits: PullRequestCommit[];
+  changedFiles: ChangedFile[];
+  fileContents?: FileContentsMap;
+  [key: string]: unknown;
+}
+
+export const buildPrDescriptionPrompt: PromptFn<PrDescriptionContext> = (ctx) => {
+  // 验证必需的输入参数
+  validateArray(ctx.commits, "commits");
+  validateArray(ctx.changedFiles, "changedFiles");
+
+  const commitMessages = ctx.commits
+    .map((c) => `- ${c.sha?.slice(0, 7)}: ${c.commit?.message?.split("\n")[0]}`)
+    .join("\n");
+  const fileChanges = ctx.changedFiles
+    .slice(0, MEMORY_LIMITS.MAX_FILES)
+    .map((f) => `- ${f.filename} (${f.status})`)
+    .join("\n");
+
+  // 构建代码变更内容（只包含变更行，优化内存使用）
+  let codeChangesSection = "";
+  if (ctx.fileContents && ctx.fileContents.size > 0) {
+    const codeSnippets: string[] = [];
+    let totalLength = 0;
+
+    // 使用 Map.entries() 进行更高效的迭代
+    for (const [filename, lines] of ctx.fileContents) {
+      if (totalLength >= MEMORY_LIMITS.MAX_TOTAL_LENGTH) break;
+
+      // 只提取有变更的行（commitHash 不是 "-------"）
+      const changedLines = lines
+        .map(([hash, code], idx) => (hash !== "-------" ? `${idx + 1}: ${code}` : null))
+        .filter(Boolean);
+
+      if (changedLines.length > 0) {
+        // 限制每个文件的代码行数，避免单个文件占用过多内存
+        const limitedLines = changedLines.slice(0, MEMORY_LIMITS.MAX_SNIPPET_LENGTH);
+        const snippet = `### ${filename}\n\`\`\`\n${limitedLines.join("\n")}\n\`\`\``;
+
+        // 检查添加此片段是否会超过内存限制
+        if (totalLength + snippet.length <= MEMORY_LIMITS.MAX_TOTAL_LENGTH) {
+          codeSnippets.push(snippet);
+          totalLength += snippet.length;
+        } else {
+          // 如果添加当前片段会超过限制，尝试截断它
+          const remainingLength = MEMORY_LIMITS.MAX_TOTAL_LENGTH - totalLength;
+          if (remainingLength > 100) {
+            // 至少保留 100 字符的片段
+            // snippet 格式为 "### filename\n```\ncode\n```"
+            // 截断时去掉结尾的 ``` 再追加，避免双重代码块
+            const closingTag = "\n```";
+            const contentEnd = snippet.lastIndexOf(closingTag);
+            const truncateAt = Math.max(
+              0,
+              contentEnd > 0 ? Math.min(remainingLength - 20, contentEnd) : remainingLength - 20,
+            );
+            const truncatedSnippet = snippet.substring(0, truncateAt) + "\n..." + closingTag;
+            codeSnippets.push(truncatedSnippet);
+            break;
+          }
+          break;
+        }
+      }
+    }
+
+    if (codeSnippets.length > 0) {
+      codeChangesSection = `\n\n## 代码变更内容\n${codeSnippets.join("\n\n")}`;
+    }
+  }
+
+  return {
+    systemPrompt: "",
+    userPrompt: `请根据以下 PR 的 commit 记录、文件变更和代码内容，用简洁的中文总结这个 PR 实现了什么功能。
+要求：
+1. 第一行输出 PR 标题，格式必须是: Feat xxx 或 Fix xxx 或 Refactor xxx（根据变更类型选择，整体不超过 50 个字符）
+2. 空一行后输出详细描述
+3. 描述应该简明扼要，突出核心功能点
+4. 使用 Markdown 格式
+5. 不要逐条列出 commit，而是归纳总结
+6. 重点分析代码变更的实际功能
+
+## Commit 记录 (${ctx.commits.length} 个)
+${commitMessages || "无"}
+
+## 文件变更 (${ctx.changedFiles.length} 个文件)
+${fileChanges || "无"}${ctx.changedFiles.length > MEMORY_LIMITS.MAX_FILES ? `\n... 等 ${ctx.changedFiles.length - MEMORY_LIMITS.MAX_FILES} 个文件` : ""}${codeChangesSection}`,
+  };
+};
+
+/**
+ * PR 标题生成提示词
+ */
+export interface PrTitleContext {
+  commits: PullRequestCommit[];
+  changedFiles: ChangedFile[];
+  [key: string]: unknown;
+}
+
+export const buildPrTitlePrompt: PromptFn<PrTitleContext> = (ctx) => {
+  // 验证必需的输入参数
+  validateArray(ctx.commits, "commits");
+  validateArray(ctx.changedFiles, "changedFiles");
+
+  const commitMessages = ctx.commits
+    .slice(0, MEMORY_LIMITS.MAX_COMMITS)
+    .map((c) => c.commit?.message?.split("\n")[0])
+    .filter(Boolean)
+    .join("\n");
+  const fileChanges = ctx.changedFiles
+    .slice(0, MEMORY_LIMITS.MAX_FILES_FOR_TITLE)
+    .map((f) => `${f.filename} (${f.status})`)
+    .join("\n");
+
+  return {
+    systemPrompt: "",
+    userPrompt: `请根据以下 commit 记录和文件变更，生成一个简短的 PR 标题。
+要求：
+1. 格式必须是: Feat: xxx 或 Fix: xxx 或 Refactor: xxx
+2. 根据变更内容选择合适的前缀（新功能用 Feat，修复用 Fix，重构用 Refactor）
+3. xxx 部分用简短的中文描述（整体不超过 50 个字符）
+4. 只输出标题，不要加任何解释
+
+Commit 记录:
+${commitMessages || "无"}
+
+文件变更:
+${fileChanges || "无"}`,
+  };
+};

package/src/prompt/schemas.ts

@@ -0,0 +1,106 @@
+import type { LlmJsonPutSchema } from "@spaceflow/core";
+
+/**
+ * 代码审查结果 JSON Schema
+ */
+export const REVIEW_SCHEMA: LlmJsonPutSchema = {
+  type: "object",
+  properties: {
+    issues: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          file: { type: "string", description: "发生问题的文件路径" },
+          line: {
+            type: "string",
+            description:
+              "问题所在的行号，只支持单行或多行 (如 123 或 123-125)，不允许使用 `,` 分隔多个行号",
+          },
+          ruleId: { type: "string", description: "违反的规则 ID（如 JsTs.FileName.UpperCamel）" },
+          specFile: {
+            type: "string",
+            description: "规则来源的规范文件名（如 js&ts.file-name.md）",
+          },
+          reason: { type: "string", description: "问题的简要概括" },
+          suggestion: {
+            type: "string",
+            description:
+              "修改后的完整代码片段。要求以代码为主体，并在代码中使用详细的中文注释解释逻辑改进点。不要包含 Markdown 反引号。",
+          },
+          commit: { type: "string", description: "相关的 7 位 commit SHA" },
+          severity: {
+            type: "string",
+            description: "问题严重程度，根据规则文档中的 severity 标记确定",
+            enum: ["error", "warn"],
+          },
+        },
+        required: ["file", "line", "ruleId", "specFile", "reason"],
+        additionalProperties: false,
+      },
+    },
+    summary: { type: "string", description: "本次代码审查的整体总结" },
+  },
+  required: ["issues", "summary"],
+  additionalProperties: false,
+};
+
+/**
+ * 删除影响分析结果 JSON Schema
+ */
+export const DELETION_IMPACT_SCHEMA: LlmJsonPutSchema = {
+  type: "object",
+  properties: {
+    impacts: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          file: { type: "string", description: "被删除代码所在的文件路径" },
+          deletedCode: { type: "string", description: "被删除的代码片段摘要（前50字符）" },
+          riskLevel: {
+            type: "string",
+            enum: ["high", "medium", "low", "none"],
+            description:
+              "风险等级：high=可能导致功能异常，medium=可能影响部分功能，low=影响较小，none=无影响",
+          },
+          affectedFiles: {
+            type: "array",
+            items: { type: "string" },
+            description: "可能受影响的文件列表",
+          },
+          reason: { type: "string", description: "影响分析的详细说明" },
+          suggestion: { type: "string", description: "建议的处理方式" },
+        },
+        required: ["file", "deletedCode", "riskLevel", "affectedFiles", "reason"],
+        additionalProperties: false,
+      },
+    },
+    summary: { type: "string", description: "删除代码影响的整体总结" },
+  },
+  required: ["impacts", "summary"],
+  additionalProperties: false,
+};
+
+/**
+ * 问题验证结果 JSON Schema
+ */
+export const VERIFY_SCHEMA: LlmJsonPutSchema = {
+  type: "object",
+  properties: {
+    fixed: {
+      type: "boolean",
+      description: "问题是否已被修复",
+    },
+    valid: {
+      type: "boolean",
+      description: "问题是否有效，有效的条件就是你需要看看代码是否符合规范",
+    },
+    reason: {
+      type: "string",
+      description: "判断依据，说明为什么认为问题已修复或仍存在",
+    },
+  },
+  required: ["fixed", "valid", "reason"],
+  additionalProperties: false,
+};

package/src/prompt/types.ts

@@ -0,0 +1,53 @@
+/**
+ * 提示词回调函数类型定义
+ */
+export interface PromptContext {
+  [key: string]: unknown;
+}
+
+export interface PromptResult {
+  systemPrompt: string;
+  userPrompt: string;
+}
+
+/**
+ * 输入验证错误类
+ */
+export class PromptValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "PromptValidationError";
+  }
+}
+
+/**
+ * 输入验证工具函数
+ */
+export function validateRequired<T>(value: T | undefined | null, fieldName: string): T {
+  if (value === undefined || value === null) {
+    throw new PromptValidationError(`${fieldName} is required but was ${value}`);
+  }
+  return value;
+}
+
+export function validateNonEmptyString(
+  value: string | undefined | null,
+  fieldName: string,
+): string {
+  if (value === undefined || value === null || value.trim() === "") {
+    throw new PromptValidationError(`${fieldName} is required and cannot be empty`);
+  }
+  return value;
+}
+
+export function validateArray<T>(value: T[] | undefined | null, fieldName: string): T[] {
+  if (!Array.isArray(value)) {
+    throw new PromptValidationError(`${fieldName} must be an array but was ${typeof value}`);
+  }
+  return value;
+}
+
+/**
+ * 提示词函数类型 - 接收上下文，返回 systemPrompt 和 userPrompt
+ */
+export type PromptFn<T extends PromptContext = PromptContext> = (ctx: T) => PromptResult;

package/src/review-context.ts

@@ -28,6 +28,7 @@ export interface ReviewContext extends ReviewOptions {
   specSources: string[];
   verbose?: VerboseLevel;
   includes?: string[];
+  whenModifiedCode?: string[];
   files?: string[];
   commits?: string[];
   concurrency?: number;
@@ -64,6 +65,9 @@ export class ReviewContextBuilder {
 
   async getContextFromEnv(options: ReviewOptions): Promise<ReviewContext> {
     const reviewConf = this.config.getPluginConfig<ReviewConfig>("review");
+    if (shouldLog(options.verbose, 2)) {
+      console.log(`[getContextFromEnv] reviewConf: ${JSON.stringify(reviewConf)}`);
+    }
     const ciConf = this.config.get<CiConfig>("ci");
     const repository = ciConf?.repository;
 
@@ -152,6 +156,12 @@ export class ReviewContextBuilder {
     }
 
     // 合并参数优先级：命令行 > PR 标题 > 配置文件 > 默认值
+    const ctxIncludes = options.includes ?? titleOptions.includes ?? reviewConf.includes;
+    if (shouldLog(options.verbose, 2)) {
+      console.log(
+        `[getContextFromEnv] includes: commandLine=${JSON.stringify(options.includes)}, title=${JSON.stringify(titleOptions.includes)}, config=${JSON.stringify(reviewConf.includes)}, final=${JSON.stringify(ctxIncludes)}`,
+      );
+    }
     return {
       owner,
       repo,
@@ -162,7 +172,8 @@ export class ReviewContextBuilder {
       dryRun: options.dryRun || titleOptions.dryRun || false,
       ci: options.ci ?? false,
       verbose: normalizeVerbose(options.verbose ?? titleOptions.verbose),
-      includes: options.includes ?? titleOptions.includes ?? reviewConf.includes,
+      includes: ctxIncludes,
+      whenModifiedCode: options.whenModifiedCode ?? reviewConf.whenModifiedCode,
       llmMode: options.llmMode ?? titleOptions.llmMode ?? reviewConf.llmMode,
       files: this.normalizeFilePaths(options.files),
       commits: options.commits,
@@ -193,9 +204,10 @@ export class ReviewContextBuilder {
       flush: options.flush ?? false,
       eventAction: options.eventAction,
       localMode,
-      skipDuplicateWorkflow:
-        options.skipDuplicateWorkflow ?? reviewConf.skipDuplicateWorkflow ?? false,
+      duplicateWorkflowResolved:
+        options.duplicateWorkflowResolved ?? reviewConf.duplicateWorkflowResolved ?? "delete",
       autoApprove: options.autoApprove ?? reviewConf.autoApprove ?? false,
+      systemRules: options.systemRules ?? reviewConf.systemRules,
     };
   }
 
@@ -390,14 +402,26 @@ export class ReviewContextBuilder {
     // 为每个 issue 填充 author
     return issues.map((issue) => {
       if (issue.author) {
+        const shortHash = issue.commit?.slice(0, 7);
+        if (shortHash?.includes("---")) {
+          return { ...issue, commit: undefined, valid: "false" };
+        }
         if (shouldLog(verbose, 2)) {
           console.log(`[fillIssueAuthors] issue already has author: ${issue.author.login}`);
         }
         return issue;
       }
       const shortHash = issue.commit?.slice(0, 7);
-      const author =
-        shortHash && !shortHash.includes("---") ? commitAuthorMap.get(shortHash) : undefined;
+      const isValidHash = Boolean(shortHash && !shortHash.includes("---"));
+      if (!isValidHash) {
+        if (shouldLog(verbose, 2)) {
+          console.log(
+            `[fillIssueAuthors] issue: file=${issue.file}, commit=${issue.commit} is invalid hash, marking as invalid`,
+          );
+        }
+        return { ...issue, commit: undefined, valid: "false" };
+      }
+      const author = commitAuthorMap.get(shortHash!);
       if (shouldLog(verbose, 2)) {
         console.log(
           `[fillIssueAuthors] issue: file=${issue.file}, commit=${issue.commit}, shortHash=${shortHash}, foundAuthor=${author?.login}, finalAuthor=${(author || defaultAuthor)?.login}`,

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

@@ -3,6 +3,7 @@ import {
   parseIncludePattern,
   filterFilesByIncludes,
   extractGlobsFromIncludes,
+  extractCodeBlockTypes,
 } from "./review-includes-filter";
 
 describe("review-includes-filter", () => {
@@ -216,6 +217,15 @@ describe("review-includes-filter", () => {
       const glFiles = [{ filename: "src/old.ts", status: "deleted" }];
       expect(filterFilesByIncludes(glFiles, [`deleted|${glob}`])).toHaveLength(1);
     });
+
+    it("全量 diff 语义：文件在当前分支首次引入后被多次修改，status 仍为 added，added| 始终匹配", () => {
+      // 场景：a.ts 在 commit1 创建（status=added），在 commit2 修改
+      // 全量 diff（当前分支 vs base）时，compare API 返回的 status 仍为 added
+      // 因此 added|*.ts 在后续每次 review 中都能匹配到该文件
+      const diffFiles = [{ filename: "src/a.ts", status: "added" }];
+      const result = filterFilesByIncludes(diffFiles, [`added|${glob}`]);
+      expect(result.map((f) => f.filename)).toEqual(["src/a.ts"]);
+    });
   });
 
   describe("extractGlobsFromIncludes", () => {
@@ -245,4 +255,30 @@ describe("review-includes-filter", () => {
       expect(extractGlobsFromIncludes([])).toEqual([]);
     });
   });
+
+  describe("extractCodeBlockTypes", () => {
+    it("提取纯类型名", () => {
+      const result = extractCodeBlockTypes(["function", "class"]);
+      expect(result).toEqual(["function", "class"]);
+    });
+
+    it("status|code-* 语法不被识别，返回空", () => {
+      const result = extractCodeBlockTypes(["added|code-function", "added|code-class"]);
+      expect(result).toEqual([]);
+    });
+
+    it("混合：纯类型名保留，status 前缀语法忽略", () => {
+      const result = extractCodeBlockTypes(["added|code-function", "class"]);
+      expect(result).toEqual(["class"]);
+    });
+
+    it("去重：同一类型出现多次只返回一次", () => {
+      const result = extractCodeBlockTypes(["function", "function"]);
+      expect(result).toEqual(["function"]);
+    });
+
+    it("空数组返回空数组", () => {
+      expect(extractCodeBlockTypes([])).toEqual([]);
+    });
+  });
 });

package/src/review-includes-filter.ts

@@ -4,13 +4,36 @@ import micromatch from "micromatch";
  * includes 模式中的变更类型前缀
  *
  * 语法：`<status>|<glob>`，例如：
- * - `added|*\/**\/*.ts`   → 仅匹配新增文件
- * - `modified|*\/**\/*.ts` → 仅匹配修改文件
- * - `deleted|*\/**\/*.ts`  → 仅匹配删除文件
- * - `*\/**\/*.ts`          → 不限变更类型（原有行为）
+ * - `added|*\/**\/*.ts`          → 仅匹配新增文件
+ * - `modified|*\/**\/*.ts`       → 仅匹配修改文件
+ * - `deleted|*\/**\/*.ts`        → 仅匹配删除文件
+ * - `*\/**\/*.ts`               → 不限变更类型（原有行为）
+ *
+ * ## 全量 diff 语义说明
+ *
+ * 每次 review 是对当前分支与 base 分支（develop/master）的**全量 diff**，
+ * 文件的 status 由平台 compare API 给出，表示该文件**相对 base 分支**的变更类型。
+ *
+ * 因此，若 `a.ts` 是在当前分支上首次引入的（相对 base 不存在），
+ * 无论后续经过多少次 commit 修改，其 status **始终为 `added`**。
+ * 这意味着 `added|*.ts` 在后续每次 review 中都会继续匹配该文件，
+ * 这是符合预期的行为——只要文件相对 base 是"新建"的，`added|` 就应该始终生效。
  */
 export type IncludeStatusPrefix = "added" | "modified" | "deleted";
 
+/**
+ * 代码结构类型，用于 whenModifiedCode 配置
+ */
+export type CodeBlockType = "function" | "class" | "interface" | "type" | "method";
+
+export const CODE_BLOCK_TYPES: CodeBlockType[] = [
+  "function",
+  "class",
+  "interface",
+  "type",
+  "method",
+];
+
 /** status 值到前缀的映射（兼容 GitHub/GitLab/Gitea 各平台） */
 const STATUS_ALIAS: Record<string, IncludeStatusPrefix> = {
   added: "added",
@@ -51,6 +74,7 @@ export function parseIncludePattern(pattern: string): ParsedIncludePattern {
     // 前缀无法识别（如 extglob 中的 `|`），当作普通 glob 处理
     return { status: undefined, glob: pattern };
   }
+
   return { status, glob };
 }
 
@@ -78,6 +102,7 @@ export function filterFilesByIncludes<T extends FileWithStatus>(
   if (!includes || includes.length === 0) return files;
 
   const parsed = includes.map(parseIncludePattern);
+  console.log(`[filterFilesByIncludes] parsed patterns=${JSON.stringify(parsed)}`);
 
   // 排除模式（以 ! 开头），用于最终全局过滤
   const negativeGlobs = parsed
@@ -90,8 +115,13 @@ export function filterFilesByIncludes<T extends FileWithStatus>(
   // 有 status 前缀的 patterns
   const statusPatterns = parsed.filter((p) => p.status !== undefined);
 
+  console.log(
+    `[filterFilesByIncludes] negativeGlobs=${JSON.stringify(negativeGlobs)}, plainGlobs=${JSON.stringify(plainGlobs)}, statusPatterns=${JSON.stringify(statusPatterns)}`,
+  );
+
   return files.filter((file) => {
     const filename = file.filename ?? "";
+    const fileStatus = STATUS_ALIAS[file.status?.toLowerCase() ?? ""] ?? "modified";
     if (!filename) return false;
 
     // 最终排除：命中排除模式的文件直接过滤掉
@@ -99,18 +129,19 @@ export function filterFilesByIncludes<T extends FileWithStatus>(
       negativeGlobs.length > 0 &&
       micromatch.isMatch(filename, negativeGlobs, { matchBase: true })
     ) {
+      console.log(`[filterFilesByIncludes] ${filename} excluded by negativeGlobs`);
       return false;
     }
 
     // 正向匹配：无前缀 glob
     if (plainGlobs.length > 0 && micromatch.isMatch(filename, plainGlobs, { matchBase: true })) {
+      console.log(`[filterFilesByIncludes] ${filename} matched plainGlobs`);
       return true;
     }
 
     // 正向匹配：有 status 前缀的 glob，按文件实际 status 过滤
     // glob 可以带 ! 前缀表示在该 status 范围内排除，如 added|!**/*.spec.ts
     if (statusPatterns.length > 0) {
-      const fileStatus = STATUS_ALIAS[file.status?.toLowerCase() ?? ""] ?? "modified";
       // 按 status 分组，每组内正向 glob + 排除 glob 合并后批量匹配
       const matchingStatusGlobs = statusPatterns
         .filter(({ status }) => status === fileStatus)
@@ -126,11 +157,17 @@ export function filterFilesByIncludes<T extends FileWithStatus>(
           const matchesNegative =
             negativeStatusGlobs.length > 0 &&
             micromatch.isMatch(filename, negativeStatusGlobs, { matchBase: true });
-          if (matchesPositive && !matchesNegative) return true;
+          if (matchesPositive && !matchesNegative) {
+            console.log(
+              `[filterFilesByIncludes] ${filename} (status=${fileStatus}) matched statusPatterns`,
+            );
+            return true;
+          }
         }
       }
     }
 
+    console.log(`[filterFilesByIncludes] ${filename} (status=${fileStatus}) NOT matched`);
     return false;
   });
 }
@@ -140,5 +177,20 @@ export function filterFilesByIncludes<T extends FileWithStatus>(
  * 带 status 前缀的模式会去掉前缀，仅保留 glob 部分。
  */
 export function extractGlobsFromIncludes(includes: string[]): string[] {
-  return includes.map((p) => parseIncludePattern(p).glob);
+  return includes.map((p) => parseIncludePattern(p).glob).filter((g) => g.length > 0);
+}
+
+/**
+ * 从 whenModifiedCode 配置中解析代码结构过滤类型。
+ * 只接受简单的类型名称，如 "function"、"class"、"interface"、"type"、"method"
+ */
+export function extractCodeBlockTypes(whenModifiedCode: string[]): CodeBlockType[] {
+  const types = new Set<CodeBlockType>();
+  for (const entry of whenModifiedCode) {
+    const trimmed = entry.trim();
+    if ((CODE_BLOCK_TYPES as string[]).includes(trimmed)) {
+      types.add(trimmed as CodeBlockType);
+    }
+  }
+  return [...types];
 }

package/src/review-issue-filter.ts

@@ -20,7 +20,7 @@ import {
   FileContentLine,
 } from "./review-spec";
 import { IssueVerifyService } from "./issue-verify.service";
-import { generateIssueKey } from "./review-pr-comment-utils";
+import { generateIssueKey } from "./utils/review-pr-comment";
 import type { ReviewContext } from "./review-context";
 
 export class ReviewIssueFilter {