@spaceflow/review 0.76.0 → 0.78.0

package/src/prompt/deletion-impact.ts

@@ -0,0 +1,105 @@
+import type { PromptFn } from "./types";
+import { validateArray, validateRequired } from "./types";
+import type { DeletedCodeBlock } from "../deletion-impact.service";
+
+/**
+ * 删除影响分析 - 标准 LLM 模式
+ */
+export interface DeletionImpactContext {
+  deletedBlocks: DeletedCodeBlock[];
+  references: Map<string, string[]>;
+  [key: string]: unknown;
+}
+
+const DELETION_IMPACT_SYSTEM = `你是一个代码审查专家，专门分析删除代码可能带来的影响。
+
+## 任务
+分析以下被删除的代码块，判断删除这些代码是否会影响到其他功能。
+
+## 分析要点
+1. **功能依赖**: 被删除的代码是否被其他模块调用或依赖
+2. **接口变更**: 删除是否会导致 API 或接口不兼容
+3. **副作用**: 删除是否会影响系统的其他行为
+4. **数据流**: 删除是否会中断数据处理流程
+
+## 风险等级判断标准
+- **high**: 删除的代码被其他文件直接调用，删除后会导致编译错误或运行时异常
+- **medium**: 删除的代码可能影响某些功能的行为，但不会导致直接错误
+- **low**: 删除的代码影响较小，可能只是清理无用代码
+- **none**: 删除的代码确实是无用代码，不会产生任何影响
+
+## 输出要求
+- 对每个有风险的删除块给出详细分析
+- 如果删除是安全的，也要说明原因
+- 提供具体的建议`;
+
+function buildDeletedCodeSection(ctx: DeletionImpactContext): string {
+  return ctx.deletedBlocks
+    .map((block, index) => {
+      const refs = ctx.references.get(`${block.file}:${block.startLine}-${block.endLine}`) || [];
+      return `### 删除块 ${index + 1}: ${block.file}:${block.startLine}-${block.endLine}\n\n\`\`\`\n${block.content}\n\`\`\`\n\n可能引用此代码的文件: ${refs.length > 0 ? refs.join(", ") : "未发现直接引用"}\n`;
+    })
+    .join("\n");
+}
+
+export const buildDeletionImpactPrompt: PromptFn<DeletionImpactContext> = (ctx) => {
+  validateArray(ctx.deletedBlocks, "deletedBlocks");
+  validateRequired(ctx.references, "references");
+  return {
+    systemPrompt: DELETION_IMPACT_SYSTEM,
+    userPrompt: `## 被删除的代码块\n\n${buildDeletedCodeSection(ctx)}\n请分析这些删除操作可能带来的影响。`,
+  };
+};
+
+/** @deprecated 使用 buildDeletionImpactPrompt */
+export const buildDeletionImpactSystemPrompt: PromptFn<DeletionImpactContext> = (ctx) =>
+  buildDeletionImpactPrompt(ctx);
+
+/** @deprecated 使用 buildDeletionImpactPrompt */
+export const buildDeletionImpactUserPrompt: PromptFn<DeletionImpactContext> = (ctx) =>
+  buildDeletionImpactPrompt(ctx);
+
+const DELETION_IMPACT_AGENT_SYSTEM = `你是一个资深代码架构师，擅长分析代码变更的影响范围和潜在风险。
+
+## 任务
+深入分析以下被删除的代码块，评估删除操作对代码库的影响。
+
+## 你的能力
+你可以使用以下工具来深入分析代码：
+- **Read**: 读取文件内容，查看被删除代码的完整上下文
+- **Grep**: 搜索代码库，查找对被删除代码的引用
+- **Glob**: 查找匹配模式的文件
+
+## 分析流程
+1. 首先阅读被删除代码的上下文，理解其功能
+2. 使用 Grep 搜索代码库中对这些代码的引用
+3. 分析引用处的代码，判断删除后的影响
+4. 给出风险评估和建议
+
+## 风险等级判断标准
+- **high**: 删除的代码被其他文件直接调用，删除后会导致编译错误或运行时异常
+- **medium**: 删除的代码可能影响某些功能的行为，但不会导致直接错误
+- **low**: 删除的代码影响较小，可能只是清理无用代码
+- **none**: 删除的代码确实是无用代码，不会产生任何影响
+
+## 输出要求
+- 对每个有风险的删除块给出详细分析
+- 如果删除是安全的，也要说明原因
+- 提供具体的建议`;
+
+export const buildDeletionImpactAgentPrompt: PromptFn<DeletionImpactContext> = (ctx) => {
+  validateArray(ctx.deletedBlocks, "deletedBlocks");
+  validateRequired(ctx.references, "references");
+  return {
+    systemPrompt: DELETION_IMPACT_AGENT_SYSTEM,
+    userPrompt: `## 被删除的代码块\n\n${buildDeletedCodeSection(ctx)}\n## 补充说明\n\n请使用你的工具能力深入分析这些删除操作可能带来的影响。\n- 如果需要查看更多上下文，请读取相关文件\n- 如果需要确认引用关系，请搜索代码库\n- 分析完成后，给出结构化的影响评估`,
+  };
+};
+
+/** @deprecated 使用 buildDeletionImpactAgentPrompt */
+export const buildDeletionImpactAgentSystemPrompt: PromptFn<DeletionImpactContext> = (ctx) =>
+  buildDeletionImpactAgentPrompt(ctx);
+
+/** @deprecated 使用 buildDeletionImpactAgentPrompt */
+export const buildDeletionImpactAgentUserPrompt: PromptFn<DeletionImpactContext> = (ctx) =>
+  buildDeletionImpactAgentPrompt(ctx);

package/src/prompt/index.ts

@@ -0,0 +1,37 @@
+// 统一导出所有提示词
+
+// 类型定义
+export type { PromptFn, PromptContext, PromptResult } from "./types";
+
+// JSON Schemas
+export { REVIEW_SCHEMA, DELETION_IMPACT_SCHEMA, VERIFY_SCHEMA } from "./schemas";
+
+// 代码审查提示词
+export {
+  buildCodeReviewSystemPrompt,
+  buildFileReviewPrompt,
+  type CodeReviewSystemContext,
+  type FileReviewContext,
+} from "./code-review";
+
+// PR 描述生成提示词
+export {
+  buildPrDescriptionPrompt,
+  buildPrTitlePrompt,
+  type PrDescriptionContext,
+  type PrTitleContext,
+} from "./pr-description";
+
+// 删除影响分析提示词
+export {
+  buildDeletionImpactPrompt,
+  buildDeletionImpactAgentPrompt,
+  buildDeletionImpactSystemPrompt,
+  buildDeletionImpactUserPrompt,
+  buildDeletionImpactAgentSystemPrompt,
+  buildDeletionImpactAgentUserPrompt,
+  type DeletionImpactContext,
+} from "./deletion-impact";
+
+// 问题验证提示词
+export { buildIssueVerifyPrompt, type IssueVerifyContext } from "./issue-verify";

package/src/prompt/issue-verify.ts

@@ -0,0 +1,86 @@
+import type { PromptFn } from "./types";
+import { validateRequired, validateArray } from "./types";
+import type { ReviewIssue, ReviewRule, ReviewSpec, FileContentLine } from "../review-spec";
+
+/**
+ * 问题验证提示词上下文
+ */
+export interface IssueVerifyContext {
+  issue: ReviewIssue;
+  fileContent: FileContentLine[];
+  ruleInfo: { rule: ReviewRule; spec: ReviewSpec } | null;
+  specsSection?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * 构建问题验证提示词
+ */
+export const buildIssueVerifyPrompt: PromptFn<IssueVerifyContext> = (ctx) => {
+  // 验证必需的输入参数
+  validateRequired(ctx.issue, "issue");
+  validateArray(ctx.fileContent, "fileContent");
+
+  const padWidth = String(ctx.fileContent.length).length;
+  const linesWithNumbers = ctx.fileContent
+    .map(([, line], index) => `${String(index + 1).padStart(padWidth)}| ${line}`)
+    .join("\n");
+
+  const systemPrompt = `你是一个代码审查专家。你的任务是判断之前发现的一个代码问题：
+1. 是否有效（是否真的违反了规则）
+2. 是否已经被修复
+
+请仔细分析当前的代码内容。
+
+## 输出要求
+- valid: 布尔值，true 表示问题有效（代码确实违反了规则），false 表示问题无效（误报）
+- fixed: 布尔值，true 表示问题已经被修复，false 表示问题仍然存在
+- reason: 判断依据
+
+## 判断标准
+
+### valid 判断
+- 根据规则 ID 和问题描述，判断代码是否真的违反了该规则
+- 如果问题描述与实际代码不符，valid 为 false
+- 如果规则不适用于该代码场景，valid 为 false
+
+### fixed 判断
+- 只有当问题所在的代码已被修改，且修改后的代码不再违反规则时，fixed 才为 true
+- 如果问题所在的代码仍然存在且仍违反规则，fixed 必须为 false
+- 如果代码行号发生变化但问题本质仍存在，fixed 必须为 false
+
+## 重要提醒
+- valid=false 时，fixed 的值无意义（无效问题无需修复）
+- 请确保 valid 和 fixed 的值与 reason 的描述一致！`;
+
+  // 构建规则定义部分
+  let ruleSection = "";
+  if (ctx.specsSection) {
+    ruleSection = ctx.specsSection;
+  } else if (ctx.ruleInfo) {
+    const { spec, rule } = ctx.ruleInfo;
+    ruleSection = `### ${spec.filename} (${spec.type})\n\n${spec.content.slice(0, 200)}...\n\n#### 规则\n- ${rule.id}: ${rule.title}\n  ${rule.description}`;
+  }
+
+  const userPrompt = `## 规则定义
+
+${ruleSection}
+
+## 之前发现的问题
+
+- **文件**: ${ctx.issue.file}
+- **行号**: ${ctx.issue.line}
+- **规则**: ${ctx.issue.ruleId} (来自 ${ctx.issue.specFile})
+- **问题描述**: ${ctx.issue.reason}
+${ctx.issue.suggestion ? `- **原建议**: ${ctx.issue.suggestion}` : ""}
+
+## 当前文件内容
+
+\`\`\`
+${linesWithNumbers}
+\`\`\`
+
+请判断这个问题是否有效，以及是否已经被修复。`;
+
+  return { systemPrompt, userPrompt };
+};

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;