@spaceflow/review 0.29.1

package/src/review-spec/types.ts

@@ -0,0 +1,143 @@
+export type Severity = "off" | "warn" | "error";
+
+/** 文件内容行：[commitHash, lineCode]，commitHash 为 7 位短 hash 或 "-------" 表示非变更行 */
+export type FileContentLine = [string, string];
+
+/** 文件内容映射：filename -> 每行的 [commitHash, lineCode] 数组 */
+export type FileContentsMap = Map<string, FileContentLine[]>;
+
+export const SEVERITY_EMOJI: Record<Severity, string> = {
+  off: "⚪",
+  warn: "🟡",
+  error: "🔴",
+};
+
+export interface ReviewSpec {
+  filename: string;
+  extensions: string[];
+  type: string;
+  content: string;
+  rules: ReviewRule[];
+  overrides: string[]; // 文件级别的 override
+  severity: Severity; // 文件级别的默认 severity
+  includes: string[]; // 文件级别的 includes，只有匹配的文件才应用此规范
+}
+
+export interface RuleExample {
+  lang: string;
+  code: string;
+  type: "good" | "bad";
+}
+
+export interface ReviewRule {
+  id: string;
+  title: string;
+  description: string;
+  examples: RuleExample[];
+  overrides: string[]; // 规则级别的 override
+  severity?: Severity; // 规则级别的 severity，可覆盖文件级别
+  includes?: string[]; // 规则级别的 includes，可覆盖文件级别
+}
+
+/** 问题的 Reaction 记录 */
+export interface IssueReaction {
+  /** reaction 内容，如 +1, -1, laugh, hooray, confused, heart, rocket, eyes */
+  content: string;
+  /** 点击该 reaction 的用户列表 */
+  users: string[];
+}
+
+/** 用户信息 */
+export interface UserInfo {
+  /** 用户 ID */
+  id?: string;
+  /** 用户登录名 */
+  login: string;
+}
+
+/** 问题评论的回复记录 */
+export interface IssueReply {
+  /** 回复用户 */
+  user: UserInfo;
+  /** 回复内容 */
+  body: string;
+  /** 回复时间 */
+  createdAt: string;
+}
+
+export interface ReviewIssue {
+  file: string;
+  line: string; // 格式 12 或者 12-14
+  code: string; // 当前行代码, 去除首尾空白
+  ruleId: string;
+  specFile: string;
+  reason: string;
+  date?: string; // 发现问题的时间
+  fixed?: string; // 修复时间
+  valid?: string; // 问题是否有效
+  suggestion?: string;
+  commit?: string;
+  severity: Severity;
+  round: number; // 发现问题的轮次
+  /** 问题的作者 */
+  author?: UserInfo;
+  /** 问题评论的 reactions 记录 */
+  reactions?: IssueReaction[];
+  /** 问题评论的回复/聊天记录 */
+  replies?: IssueReply[];
+  /** 原始行号（行号更新前的值） */
+  originalLine?: string;
+}
+
+export interface FileSummary {
+  file: string;
+  resolved: number;
+  unresolved: number;
+  summary: string;
+}
+
+export interface DeletionImpact {
+  file: string;
+  deletedCode: string;
+  riskLevel: "high" | "medium" | "low" | "none";
+  affectedFiles: string[];
+  reason: string;
+  suggestion?: string;
+}
+
+export interface DeletionImpactResult {
+  impacts: DeletionImpact[];
+  summary: string;
+}
+
+/** Review 统计信息 */
+export interface ReviewStats {
+  /** 总问题数 */
+  total: number;
+  /** 已修复数 */
+  fixed: number;
+  /** 无效问题数 */
+  invalid: number;
+  /** 待处理数 */
+  pending: number;
+  /** 修复率 (0-100) */
+  fixRate: number;
+}
+
+export interface ReviewResult {
+  success: boolean;
+  /**
+   * AI 生成的 PR 标题
+   */
+  title?: string;
+  /**
+   * 通过 commit 和 文件总结一下这个 PR 开发的什么功能
+   */
+  description: string;
+  issues: ReviewIssue[];
+  summary: FileSummary[];
+  deletionImpact?: DeletionImpactResult;
+  round: number; // 当前 review 的轮次
+  /** 问题统计信息 */
+  stats?: ReviewStats;
+}

package/src/review.command.ts

@@ -0,0 +1,244 @@
+import { Command, CommandRunner, Option, t } from "@spaceflow/core";
+import type { LLMMode, VerboseLevel } from "@spaceflow/core";
+import type { AnalyzeDeletionsMode } from "./review.config";
+import type { ReportFormat } from "./review-report";
+import { ReviewService } from "./review.service";
+
+export interface ReviewOptions {
+  dryRun: boolean;
+  ci: boolean;
+  prNumber?: number;
+  base?: string;
+  head?: string;
+  references?: string[];
+  verbose?: VerboseLevel;
+  includes?: string[];
+  llmMode?: LLMMode;
+  files?: string[];
+  commits?: string[];
+  verifyFixes?: boolean;
+  verifyConcurrency?: number;
+  analyzeDeletions?: AnalyzeDeletionsMode;
+  /** 仅执行删除代码分析，跳过常规代码审查 */
+  deletionOnly?: boolean;
+  /** 删除代码分析模式：openai 使用标准模式，claude-agent 使用 Agent 模式 */
+  deletionAnalysisMode?: LLMMode;
+  /** 输出格式：markdown, terminal, json。不指定则智能选择 */
+  outputFormat?: ReportFormat;
+  /** 是否使用 AI 生成 PR 功能描述 */
+  generateDescription?: boolean;
+  /** 显示所有问题，不过滤非变更行的问题 */
+  showAll?: boolean;
+  /** PR 事件类型（opened, synchronize, closed 等） */
+  eventAction?: string;
+  concurrency?: number;
+  timeout?: number;
+  retries?: number;
+  retryDelay?: number;
+}
+
+/**
+ * Review 命令
+ *
+ * 在 GitHub Actions 中执行，用于自动代码审查
+ *
+ * 环境变量：
+ * - GITHUB_TOKEN: GitHub API Token
+ * - GITHUB_REPOSITORY: 仓库名称 (owner/repo 格式)
+ * - GITHUB_REF_NAME: 当前分支名称
+ * - GITHUB_EVENT_PATH: 事件文件路径（包含 PR 信息）
+ */
+@Command({
+  name: "review",
+  description: t("review:description"),
+})
+export class ReviewCommand extends CommandRunner {
+  constructor(protected readonly reviewService: ReviewService) {
+    super();
+  }
+
+  async run(_passedParams: string[], options: ReviewOptions): Promise<void> {
+    try {
+      const context = await this.reviewService.getContextFromEnv(options);
+      await this.reviewService.execute(context);
+    } catch (error) {
+      if (error instanceof Error) {
+        console.error(t("common.executionFailed", { error: error.message }));
+        if (error.stack) {
+          console.error(t("common.stackTrace", { stack: error.stack }));
+        }
+      } else {
+        console.error(t("common.executionFailed", { error }));
+      }
+      process.exit(1);
+    }
+  }
+
+  @Option({
+    flags: "-d, --dry-run",
+    description: t("review:options.dryRun"),
+  })
+  parseDryRun(val: boolean): boolean {
+    return val;
+  }
+
+  @Option({
+    flags: "-c, --ci",
+    description: t("common.options.ci"),
+  })
+  parseCi(val: boolean): boolean {
+    return val;
+  }
+
+  @Option({
+    flags: "-p, --pr-number <number>",
+    description: t("review:options.prNumber"),
+  })
+  parsePrNumber(val: string): number {
+    return parseInt(val, 10);
+  }
+
+  @Option({
+    flags: "-b, --base <ref>",
+    description: t("review:options.base"),
+  })
+  parseBase(val: string): string {
+    return val;
+  }
+
+  @Option({
+    flags: "--head <ref>",
+    description: t("review:options.head"),
+  })
+  parseHead(val: string): string {
+    return val;
+  }
+
+  @Option({
+    flags: "-v, --verbose",
+    description: t("common.options.verboseDebug"),
+  })
+  parseVerbose(_val: string, previous: VerboseLevel = 0): VerboseLevel {
+    const current = typeof previous === "number" ? previous : previous ? 1 : 0;
+    return Math.min(current + 1, 3) as VerboseLevel;
+  }
+
+  @Option({
+    flags: "-i, --includes <patterns...>",
+    description: t("review:options.includes"),
+  })
+  parseIncludes(val: string, previous: string[] = []): string[] {
+    return [...previous, val];
+  }
+
+  @Option({
+    flags: "-l, --llm-mode <mode>",
+    description: t("review:options.llmMode"),
+    choices: ["claude-code", "openai", "gemini"],
+  })
+  parseLlmMode(val: string): LLMMode {
+    return val as LLMMode;
+  }
+
+  @Option({
+    flags: "-f, --files <files...>",
+    description: t("review:options.files"),
+  })
+  parseFiles(val: string, previous: string[] = []): string[] {
+    return [...previous, val];
+  }
+
+  @Option({
+    flags: "--commits <commits...>",
+    description: t("review:options.commits"),
+  })
+  parseCommits(val: string, previous: string[] = []): string[] {
+    return [...previous, val];
+  }
+
+  @Option({
+    flags: "--verify-fixes",
+    description: t("review:options.verifyFixes"),
+  })
+  parseVerifyFixes(val: boolean): boolean {
+    return val;
+  }
+
+  @Option({
+    flags: "--no-verify-fixes",
+    description: t("review:options.noVerifyFixes"),
+  })
+  parseNoVerifyFixes(val: boolean): boolean {
+    return !val;
+  }
+
+  @Option({
+    flags: "--verify-concurrency <number>",
+    description: t("review:options.verifyConcurrency"),
+  })
+  parseVerifyConcurrency(val: string): number {
+    return parseInt(val, 10);
+  }
+
+  @Option({
+    flags: "--analyze-deletions [mode]",
+    description: t("review:options.analyzeDeletions"),
+  })
+  parseAnalyzeDeletions(val: string | boolean): AnalyzeDeletionsMode {
+    if (val === true || val === "true") return true;
+    if (val === false || val === "false") return false;
+    if (val === "ci" || val === "pr" || val === "terminal") return val;
+    // 默认为 true（当只传 --analyze-deletions 不带值时）
+    return true;
+  }
+
+  @Option({
+    flags: "--deletion-analysis-mode <mode>",
+    description: t("review:options.deletionAnalysisMode"),
+    choices: ["openai", "claude-code"],
+  })
+  parseDeletionAnalysisMode(val: string): LLMMode {
+    return val as LLMMode;
+  }
+
+  @Option({
+    flags: "--deletion-only",
+    description: t("review:options.deletionOnly"),
+  })
+  parseDeletionOnly(val: boolean): boolean {
+    return val;
+  }
+
+  @Option({
+    flags: "-o, --output-format <format>",
+    description: t("review:options.outputFormat"),
+    choices: ["markdown", "terminal", "json"],
+  })
+  parseOutputFormat(val: string): ReportFormat {
+    return val as ReportFormat;
+  }
+
+  @Option({
+    flags: "--generate-description",
+    description: t("review:options.generateDescription"),
+  })
+  parseGenerateDescription(val: boolean): boolean {
+    return val;
+  }
+
+  @Option({
+    flags: "--show-all",
+    description: t("review:options.showAll"),
+  })
+  parseShowAll(val: boolean): boolean {
+    return val;
+  }
+
+  @Option({
+    flags: "--event-action <action>",
+    description: t("review:options.eventAction"),
+  })
+  parseEventAction(val: string): string {
+    return val;
+  }
+}

package/src/review.config.ts

@@ -0,0 +1,58 @@
+import { z } from "@spaceflow/core";
+
+/** LLM 模式 schema（与 core 中的 LLMMode 保持一致） */
+const llmModeSchema = z.enum(["claude-code", "openai", "gemini", "open-code"]);
+
+/** 删除代码分析模式 schema */
+const analyzeDeletionsModeSchema = z.union([z.boolean(), z.enum(["ci", "pr", "terminal"])]);
+
+/** 审查规则严重级别 schema */
+const severitySchema = z.enum(["off", "warn", "error"]);
+
+/** 变更文件处理策略 schema */
+const invalidateChangedFilesSchema = z.enum(["invalidate", "keep", "off"]);
+
+/** review 命令配置 schema（LLM 敏感配置由系统 llm.config.ts 管理） */
+export const reviewSchema = () =>
+  z.object({
+    references: z.array(z.string()).optional(),
+    llmMode: llmModeSchema.default("openai").optional(),
+    includes: z.array(z.string()).optional(),
+    rules: z.record(z.string(), severitySchema).optional(),
+    verifyFixes: z.boolean().default(false),
+    verifyFixesConcurrency: z.number().default(10).optional(),
+    analyzeDeletions: analyzeDeletionsModeSchema.default(false),
+    deletionAnalysisMode: llmModeSchema.default("openai").optional(),
+    lineComments: z.boolean().default(false),
+    generateDescription: z.boolean().default(false).optional(),
+    autoUpdatePrTitle: z.boolean().default(false).optional(),
+    concurrency: z.number().default(5).optional(),
+    timeout: z.number().optional(),
+    retries: z.number().default(0).optional(),
+    retryDelay: z.number().default(1000).optional(),
+    invalidateChangedFiles: invalidateChangedFilesSchema.default("invalidate").optional(),
+  });
+
+/**
+ * 变更文件处理策略
+ * - 'invalidate': 将变更文件的历史问题标记为无效（默认）
+ * - 'keep': 保留历史问题，不做处理
+ * - 'off': 关闭此功能
+ */
+export type InvalidateChangedFilesMode = z.infer<typeof invalidateChangedFilesSchema>;
+
+/** review 配置类型（从 schema 推导） */
+export type ReviewConfig = z.infer<ReturnType<typeof reviewSchema>>;
+
+/**
+ * 删除代码分析模式
+ * - true: 始终启用
+ * - false: 始终禁用
+ * - 'ci': 仅在 CI 环境中启用
+ * - 'pr': 仅在 PR 环境中启用
+ * - 'terminal': 仅在终端环境中启用
+ */
+export type AnalyzeDeletionsMode = z.infer<typeof analyzeDeletionsModeSchema>;
+
+/** 审查规则严重级别 */
+export type Severity = z.infer<typeof severitySchema>;

package/src/review.mcp.ts

@@ -0,0 +1,184 @@
+/**
+ * Review MCP 服务
+ * 提供代码审查规则查询的 MCP 工具
+ */
+
+import { McpServer, McpTool, ConfigReaderService, t } from "@spaceflow/core";
+import { ReviewSpecService } from "./review-spec/review-spec.service";
+import { join } from "path";
+import { existsSync } from "fs";
+import { ListRulesInput, GetRulesForFileInput, GetRuleDetailInput } from "./dto/mcp.dto";
+import type { ReviewConfig } from "./review.config";
+
+@McpServer({ name: "review-mcp", version: "1.0.0", description: t("review:mcp.serverDescription") })
+export class ReviewMcp {
+  constructor(
+    private readonly specService: ReviewSpecService,
+    private readonly configReader: ConfigReaderService,
+  ) {}
+
+  /**
+   * 获取项目的规则目录
+   */
+  private async getSpecDirs(cwd: string): Promise<string[]> {
+    const dirs: string[] = [];
+
+    // 1. 通过 ConfigReaderService 读取 review 配置
+    try {
+      const reviewConfig = this.configReader.getPluginConfig<ReviewConfig>("review");
+      if (reviewConfig?.references?.length) {
+        const resolved = await this.specService.resolveSpecSources(reviewConfig.references);
+        dirs.push(...resolved);
+      }
+    } catch {
+      // 忽略配置读取错误
+    }
+
+    // 2. 检查默认目录
+    const defaultDirs = [
+      join(cwd, ".claude", "skills"),
+      join(cwd, ".cursor", "skills"),
+      join(cwd, "review-specs"),
+    ];
+
+    for (const dir of defaultDirs) {
+      if (existsSync(dir)) {
+        dirs.push(dir);
+      }
+    }
+
+    return [...new Set(dirs)]; // 去重
+  }
+
+  /**
+   * 加载所有规则
+   */
+  private async loadAllSpecs(cwd: string) {
+    const specDirs = await this.getSpecDirs(cwd);
+    const allSpecs = [];
+
+    for (const dir of specDirs) {
+      const specs = await this.specService.loadReviewSpecs(dir);
+      allSpecs.push(...specs);
+    }
+
+    // 只去重，不应用 override（MCP 工具应返回所有规则，override 在实际审查时应用）
+    return this.specService.deduplicateSpecs(allSpecs);
+  }
+
+  @McpTool({
+    name: "list_rules",
+    description: t("review:mcp.listRules"),
+    dto: ListRulesInput,
+  })
+  async listRules(input: ListRulesInput) {
+    const workDir = input.cwd || process.cwd();
+    const specs = await this.loadAllSpecs(workDir);
+
+    const rules = specs.flatMap((spec) =>
+      spec.rules.map((rule) => ({
+        id: rule.id,
+        title: rule.title,
+        description: rule.description.slice(0, 200) + (rule.description.length > 200 ? "..." : ""),
+        severity: rule.severity || spec.severity,
+        extensions: spec.extensions,
+        specFile: spec.filename,
+        includes: spec.includes,
+        hasExamples: rule.examples.length > 0,
+      })),
+    );
+
+    return {
+      total: rules.length,
+      rules,
+    };
+  }
+
+  @McpTool({
+    name: "get_rules_for_file",
+    description: t("review:mcp.getRulesForFile"),
+    dto: GetRulesForFileInput,
+  })
+  async getRulesForFile(input: GetRulesForFileInput) {
+    const workDir = input.cwd || process.cwd();
+    const allSpecs = await this.loadAllSpecs(workDir);
+
+    // 根据文件过滤适用的规则
+    const applicableSpecs = this.specService.filterApplicableSpecs(allSpecs, [
+      { filename: input.filePath },
+    ]);
+
+    // 进一步根据 includes 过滤（支持规则级 includes 覆盖文件级）
+    const micromatchModule = await import("micromatch");
+    const micromatch = micromatchModule.default || micromatchModule;
+
+    const rules = applicableSpecs.flatMap((spec) =>
+      spec.rules
+        .filter((rule) => {
+          // 规则级 includes 优先于文件级
+          const includes = rule.includes || spec.includes;
+          if (includes.length === 0) return true;
+          return micromatch.isMatch(input.filePath, includes, { matchBase: true });
+        })
+        .map((rule) => ({
+          id: rule.id,
+          title: rule.title,
+          description: rule.description,
+          severity: rule.severity || spec.severity,
+          specFile: spec.filename,
+          ...(input.includeExamples && rule.examples.length > 0
+            ? {
+                examples: rule.examples.map((ex) => ({
+                  type: ex.type,
+                  lang: ex.lang,
+                  code: ex.code,
+                })),
+              }
+            : {}),
+        })),
+    );
+
+    return {
+      file: input.filePath,
+      total: rules.length,
+      rules,
+    };
+  }
+
+  @McpTool({
+    name: "get_rule_detail",
+    description: t("review:mcp.getRuleDetail"),
+    dto: GetRuleDetailInput,
+  })
+  async getRuleDetail(input: GetRuleDetailInput) {
+    const workDir = input.cwd || process.cwd();
+    const specs = await this.loadAllSpecs(workDir);
+
+    const result = this.specService.findRuleById(input.ruleId, specs);
+
+    if (!result) {
+      return { error: t("review:mcp.ruleNotFound", { ruleId: input.ruleId }) };
+    }
+
+    const { rule, spec } = result;
+
+    return {
+      id: rule.id,
+      title: rule.title,
+      description: rule.description,
+      severity: rule.severity || spec.severity,
+      specFile: spec.filename,
+      extensions: spec.extensions,
+      includes: spec.includes,
+      overrides: rule.overrides,
+      examples: rule.examples.map((ex) => ({
+        type: ex.type,
+        lang: ex.lang,
+        code: ex.code,
+      })),
+    };
+  }
+}
+
+// ReviewMcpService 类已通过 @McpServer 装饰器标记
+// CLI 的 `spaceflow mcp` 命令会自动扫描并发现该类

package/src/review.module.ts

@@ -0,0 +1,52 @@
+import {
+  Module,
+  ConfigModule,
+  ConfigService,
+  ConfigReaderModule,
+  ConfigReaderService,
+  GitProviderModule,
+  ciConfig,
+  llmConfig,
+  ClaudeSetupModule,
+  LlmProxyModule,
+  GitSdkModule,
+  type LlmConfig,
+} from "@spaceflow/core";
+import { ReviewSpecModule } from "./review-spec";
+import { ReviewReportModule } from "./review-report";
+import { ReviewCommand } from "./review.command";
+import { ReviewService } from "./review.service";
+import { IssueVerifyService } from "./issue-verify.service";
+import { DeletionImpactService } from "./deletion-impact.service";
+import { ReviewMcp } from "./review.mcp";
+import type { ReviewConfig } from "./review.config";
+
+@Module({
+  imports: [
+    ConfigModule.forFeature(ciConfig),
+    ConfigModule.forFeature(llmConfig),
+    ConfigReaderModule,
+    GitProviderModule.forFeature(),
+    ClaudeSetupModule,
+    ReviewSpecModule,
+    ReviewReportModule,
+    GitSdkModule,
+    LlmProxyModule.forRootAsync({
+      imports: [ConfigReaderModule, ConfigModule],
+      useFactory: (configReader: ConfigReaderService, configService: ConfigService) => {
+        const reviewConf = configReader.getPluginConfig<ReviewConfig>("review");
+        const llm = configService.get<LlmConfig>("llm")!;
+        return {
+          defaultAdapter: reviewConf?.llmMode || "openai",
+          claudeCode: llm.claudeCode,
+          openai: llm.openai,
+          openCode: llm.openCode,
+        };
+      },
+      inject: [ConfigReaderService, ConfigService],
+    }),
+  ],
+  providers: [ReviewCommand, ReviewService, IssueVerifyService, DeletionImpactService, ReviewMcp],
+  exports: [ReviewMcp],
+})
+export class ReviewModule {}