@spaceflow/review 4.0.0 → 5.0.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## [4.0.1](https://github.com/Lydanne/spaceflow/compare/@spaceflow/review@4.0.0...@spaceflow/review@4.0.1) (2026-04-13)
+
+### 新特性
+
+* **publish:** 限制 Bumper 仅分析当前包目录的 commit ([f01166e](https://github.com/Lydanne/spaceflow/commit/f01166e8da38c836660e61e8456958df4e0cffef))
+
+### 修复BUG
+
+* **review:** 补充审查规范格式、流程、问题生命周期和输出格式文档 ([0c6987e](https://github.com/Lydanne/spaceflow/commit/0c6987ee7eb7f3c5996a5eeb50f6d672cc5f328a))
+
+### 其他修改
+
+* **publish:** released version 1.1.0 [no ci] ([5542404](https://github.com/Lydanne/spaceflow/commit/5542404cb3bb3b3bb57ac9eabeed5f442b41e005))
+* **review-summary:** released version 4.0.0 [no ci] ([29a05d1](https://github.com/Lydanne/spaceflow/commit/29a05d101a16fc6de20263b795f85b1d836e60cf))
+
+## [4.0.0](https://github.com/Lydanne/spaceflow/compare/@spaceflow/review@3.0.0...@spaceflow/review@4.0.0) (2026-04-13)
+
+### ⚠ BREAKING CHANGES
+
+* **publish:** 修复 monorepo 格式 tag 识别问题,避免错误的 major bump
+
+### 新特性
+
+* **publish:** 修复 monorepo 格式 tag 识别问题,避免错误的 major bump ([6379b71](https://github.com/Lydanne/spaceflow/commit/6379b71f5694a814f40866020bc8dd7614399e83))
+
+### 修复BUG
+
+* **review:** 更新 README,补充本地审查、MCP 工具、系统规则等新功能说明 ([ee6942f](https://github.com/Lydanne/spaceflow/commit/ee6942fe9043aff479f0ae4d6cff1623cc8df80f))
+
+### 其他修改
+
+* **publish:** released version 1.0.0 [no ci] ([ef8afbf](https://github.com/Lydanne/spaceflow/commit/ef8afbf82aae414555b8923e068ae3f7702d30e8))
+* **review-summary:** released version 3.0.0 [no ci] ([b344696](https://github.com/Lydanne/spaceflow/commit/b344696ffaaef7957cf04e34fec5ae838982aeb8))
+
 ## [3.0.0](https://github.com/Lydanne/spaceflow/compare/@spaceflow/review@2.0.0...@spaceflow/review@3.0.0) (2026-04-13)
 
 ### 代码重构

package/README.md

@@ -159,6 +159,225 @@ spaceflow review -p 123 --fail-on-issues -l openai
 
 规则搜索目录包括：`review.references` 配置路径、`.claude/skills`、`.cursor/skills`、`review-specs`。
 
+## 审查规范格式
+
+审查规范使用 Markdown 文件定义，文件名格式为 `<extensions>.<type>.md`，放置在 `references/` 目录或远程仓库中。
+
+### 文件名约定
+
+```
+<extensions>.<type>.md
+```
+
+- **extensions** — 适用的文件扩展名，多个用 `&` 连接（如 `js&ts`、`vue`）
+- **type** — 规范类别（如 `base`、`file-name`、`nest`）
+
+示例：`js&ts.base.md` → 适用于 `.js` 和 `.ts` 文件的基础规范
+
+### 规则定义格式
+
+每条规则使用 `##` 或 `###` 标题，后跟规则 ID（用反引号方括号包裹）：
+
+```markdown
+## 规则标题 `[RuleId]`
+
+规则描述文本...
+
+> - severity `warn`
+> - override `[OverriddenRuleId]`
+> - includes `*.service.ts` `*.controller.ts`
+
+### Example: 示例标题
+
+#### Good: 正确示例
+
+```typescript
+const MAX_COUNT = 100;
+```
+
+#### Bad: 错误示例
+
+```typescript
+const maxCount = 100;
+```
+```
+
+### 规则配置项
+
+在规则描述中使用引用块（`>`）声明配置：
+
+| 配置项       | 格式                          | 说明                                                         |
+| ------------ | ----------------------------- | ------------------------------------------------------------ |
+| `severity`   | `> - severity \`warn\``       | 严重级别（`off` / `warn` / `error`），默认 `error`          |
+| `override`   | `> - override \`[RuleId]\``   | 覆盖指定规则（前缀匹配），被覆盖的规则问题会被过滤         |
+| `includes`   | `> - includes \`*.ts\` \`*.js\`` | 文件匹配模式，仅对匹配的文件生效，支持 `status|glob` 前缀 |
+
+### Override 机制
+
+Override 允许高优先级规则覆盖低优先级规则，避免重复报告：
+
+- 使用前缀匹配：`override [JsTs.FileName]` 会覆盖 `JsTs.FileName` 及其子规则（如 `JsTs.FileName.UpperCamel`）
+- 作用域感知：只有当 issue 文件匹配 override 所在 spec 的 `includes` 时才生效
+- 文件级 override 写在规范文件头部（第一个 `##` 规则之前），对所有规则生效
+
+### 远程规范引用
+
+`references` 支持以下格式：
+
+```json
+{
+  "review": {
+    "references": [
+      "./references",                                    // 本地目录
+      "https://github.com/org/repo/tree/main/specs",     // GitHub 仓库目录
+      "https://gitea.example.com/org/repo/src/branch/main/specs"  // Gitea 仓库目录
+    ]
+  }
+}
+```
+
+拉取优先级：Git Provider API → tea CLI → git clone 回退 → 本地缓存
+
+## 审查流程
+
+```
+1. 解析上下文（PR/分支/本地模式） → ReviewContext
+2. 加载审查规范（本地 + 远程） → ReviewSpec[]
+3. 获取变更文件和代码内容
+4. 系统规则检查（静态，不依赖 LLM）
+5. LLM 并行审查（按文件分发，注入匹配的规范）
+6. 问题过滤（去重、includes、override、非变更行）
+7. 历史问题验证（可选，verifyFixes）
+8. 删除代码分析（可选，analyzeDeletions）
+9. AI 生成 PR 描述（可选，generateDescription）
+10. 输出结果（PR 评论 / 终端 / JSON）
+```
+
+### 参数优先级
+
+命令行 > PR 标题参数 > 配置文件 > 默认值
+
+## 问题生命周期
+
+每个审查问题（Issue）有以下状态流转：
+
+```
+发现 → 待处理 → 已修复 / 已解决 / 无效
+```
+
+| 状态       | 标记        | 说明                                   |
+| ---------- | ----------- | -------------------------------------- |
+| 待处理     | 🔴/🟡       | 新发现的问题，尚未处理                 |
+| 已修复     | 🟢          | AI 验证代码已修改，问题不再存在         |
+| 已解决     | ⚪          | 用户手动点击 resolve                    |
+| 无效       | ❌          | AI 验证或用户标记为误报                 |
+
+严重级别对应的 Emoji：
+
+| 级别   | Emoji | 说明         |
+| ------ | ----- | ------------ |
+| error  | 🔴    | 必须修复     |
+| warn   | 🟡    | 建议修复     |
+| off    | ⚪    | 规则已关闭   |
+
+### 增量审查
+
+多次运行 review 时自动追踪问题状态：
+
+- **轮次（round）** — 每次审查递增，记录问题在哪一轮发现
+- **去重** — 相同文件+行号+规则的问题不会重复报告
+- **行号追踪** — 代码变更导致行号移动时自动更新 `originalLine`
+- **变更文件处理** — `invalidateChangedFiles` 控制变更文件的历史问题是否标记为无效
+
+## Includes 模式语法
+
+`includes` 配置支持 glob 模式和变更类型前缀：
+
+### 基本语法
+
+```json
+{
+  "includes": ["**/*.ts", "!**/*.spec.ts", "!**/*.config.ts"]
+}
+```
+
+- `!` 前缀表示排除模式
+- 使用 [micromatch](https://github.com/micromatch/micromatch) 匹配
+
+### 变更类型前缀
+
+`<status>|<glob>` 语法，仅匹配指定变更类型的文件：
+
+| 前缀        | 说明   | 示例                      |
+| ----------- | ------ | ------------------------- |
+| `added\|`    | 新增文件 | `added\|**/*.ts`           |
+| `modified\|` | 修改文件 | `modified\|**/*.ts`        |
+| `deleted\|`  | 删除文件 | `deleted\|**/*.ts`         |
+
+无前缀则不限变更类型。
+
+> 注意：文件的 status 是相对 base 分支的全量 diff 结果。例如在当前分支首次引入的文件，无论后续多少次 commit 修改，其 status 始终为 `added`。
+
+### whenModifiedCode 过滤
+
+`whenModifiedCode` 配置可进一步缩小审查范围，只关注特定代码结构：
+
+```json
+{
+  "whenModifiedCode": ["function", "class"]
+}
+```
+
+支持的类型：`function`、`class`、`interface`、`type`、`method`
+
+配置后，LLM 只会收到匹配代码块范围内的代码，其余代码被裁剪。
+
+## 输出格式
+
+### markdown（默认 PR 模式）
+
+发布为 PR Review Comment，包含：
+
+- 按文件分组的问题列表（含严重级别 Emoji）
+- 每个问题的规则 ID、发现时间、开发人员
+- 修复建议代码片段
+- 文件摘要和统计信息
+- 隐藏的 JSON 数据区（用于增量审查状态追踪）
+
+### terminal
+
+终端彩色输出，适合本地审查：
+
+- 🟢 已修复 / 🔴 待处理 error / 🟡 待处理 warn / ⚪ 已解决
+- 按文件分组的摘要和问题详情
+
+### json
+
+原始 `ReviewResult` JSON 结构化输出，适合程序化处理：
+
+```json
+{
+  "success": true,
+  "title": "AI 生成的 PR 标题",
+  "description": "PR 功能总结",
+  "issues": [...],
+  "summary": [...],
+  "deletionImpact": {...},
+  "round": 2,
+  "headSha": "abc1234",
+  "stats": {
+    "total": 10,
+    "validTotal": 8,
+    "fixed": 3,
+    "resolved": 2,
+    "invalid": 2,
+    "pending": 3,
+    "fixRate": 37.5,
+    "resolveRate": 25
+  }
+}
+```
+
 ## PR 标题参数
 
 支持在 PR 标题末尾添加参数覆盖默认配置：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spaceflow/review",
-  "version": "4.0.0",
+  "version": "5.0.0",
   "description": "Spaceflow 代码审查插件，使用 LLM 对 PR 代码进行自动审查",
   "license": "MIT",
   "author": "Lydanne",
@@ -25,10 +25,10 @@
     "@vitest/coverage-v8": "^4.0.18",
     "unplugin-swc": "^1.5.9",
     "vitest": "^4.0.18",
-    "@spaceflow/cli": "0.41.0"
+    "@spaceflow/cli": "5.0.0"
   },
   "peerDependencies": {
-    "@spaceflow/core": "0.31.0"
+    "@spaceflow/core": "5.0.0"
   },
   "spaceflow": {
     "type": "flow",

package/src/coverage/base.css

@@ -0,0 +1,224 @@
+body, html {
+  margin:0; padding: 0;
+  height: 100%;
+}
+body {
+    font-family: Helvetica Neue, Helvetica, Arial;
+    font-size: 14px;
+    color:#333;
+}
+.small { font-size: 12px; }
+*, *:after, *:before {
+  -webkit-box-sizing:border-box;
+     -moz-box-sizing:border-box;
+          box-sizing:border-box;
+  }
+h1 { font-size: 20px; margin: 0;}
+h2 { font-size: 14px; }
+pre {
+    font: 12px/1.4 Consolas, "Liberation Mono", Menlo, Courier, monospace;
+    margin: 0;
+    padding: 0;
+    -moz-tab-size: 2;
+    -o-tab-size:  2;
+    tab-size: 2;
+}
+a { color:#0074D9; text-decoration:none; }
+a:hover { text-decoration:underline; }
+.strong { font-weight: bold; }
+.space-top1 { padding: 10px 0 0 0; }
+.pad2y { padding: 20px 0; }
+.pad1y { padding: 10px 0; }
+.pad2x { padding: 0 20px; }
+.pad2 { padding: 20px; }
+.pad1 { padding: 10px; }
+.space-left2 { padding-left:55px; }
+.space-right2 { padding-right:20px; }
+.center { text-align:center; }
+.clearfix { display:block; }
+.clearfix:after {
+  content:'';
+  display:block;
+  height:0;
+  clear:both;
+  visibility:hidden;
+  }
+.fl { float: left; }
+@media only screen and (max-width:640px) {
+  .col3 { width:100%; max-width:100%; }
+  .hide-mobile { display:none!important; }
+}
+
+.quiet {
+  color: #7f7f7f;
+  color: rgba(0,0,0,0.5);
+}
+.quiet a { opacity: 0.7; }
+
+.fraction {
+  font-family: Consolas, 'Liberation Mono', Menlo, Courier, monospace;
+  font-size: 10px;
+  color: #555;
+  background: #E8E8E8;
+  padding: 4px 5px;
+  border-radius: 3px;
+  vertical-align: middle;
+}
+
+div.path a:link, div.path a:visited { color: #333; }
+table.coverage {
+  border-collapse: collapse;
+  margin: 10px 0 0 0;
+  padding: 0;
+}
+
+table.coverage td {
+  margin: 0;
+  padding: 0;
+  vertical-align: top;
+}
+table.coverage td.line-count {
+    text-align: right;
+    padding: 0 5px 0 20px;
+}
+table.coverage td.line-coverage {
+    text-align: right;
+    padding-right: 10px;
+    min-width:20px;
+}
+
+table.coverage td span.cline-any {
+    display: inline-block;
+    padding: 0 5px;
+    width: 100%;
+}
+.missing-if-branch {
+    display: inline-block;
+    margin-right: 5px;
+    border-radius: 3px;
+    position: relative;
+    padding: 0 4px;
+    background: #333;
+    color: yellow;
+}
+
+.skip-if-branch {
+    display: none;
+    margin-right: 10px;
+    position: relative;
+    padding: 0 4px;
+    background: #ccc;
+    color: white;
+}
+.missing-if-branch .typ, .skip-if-branch .typ {
+    color: inherit !important;
+}
+.coverage-summary {
+  border-collapse: collapse;
+  width: 100%;
+}
+.coverage-summary tr { border-bottom: 1px solid #bbb; }
+.keyline-all { border: 1px solid #ddd; }
+.coverage-summary td, .coverage-summary th { padding: 10px; }
+.coverage-summary tbody { border: 1px solid #bbb; }
+.coverage-summary td { border-right: 1px solid #bbb; }
+.coverage-summary td:last-child { border-right: none; }
+.coverage-summary th {
+  text-align: left;
+  font-weight: normal;
+  white-space: nowrap;
+}
+.coverage-summary th.file { border-right: none !important; }
+.coverage-summary th.pct { }
+.coverage-summary th.pic,
+.coverage-summary th.abs,
+.coverage-summary td.pct,
+.coverage-summary td.abs { text-align: right; }
+.coverage-summary td.file { white-space: nowrap;  }
+.coverage-summary td.pic { min-width: 120px !important;  }
+.coverage-summary tfoot td { }
+
+.coverage-summary .sorter {
+    height: 10px;
+    width: 7px;
+    display: inline-block;
+    margin-left: 0.5em;
+    background: url(sort-arrow-sprite.png) no-repeat scroll 0 0 transparent;
+}
+.coverage-summary .sorted .sorter {
+    background-position: 0 -20px;
+}
+.coverage-summary .sorted-desc .sorter {
+    background-position: 0 -10px;
+}
+.status-line {  height: 10px; }
+/* yellow */
+.cbranch-no { background: yellow !important; color: #111; }
+/* dark red */
+.red.solid, .status-line.low, .low .cover-fill { background:#C21F39 }
+.low .chart { border:1px solid #C21F39 }
+.highlighted,
+.highlighted .cstat-no, .highlighted .fstat-no, .highlighted .cbranch-no{
+  background: #C21F39 !important;
+}
+/* medium red */
+.cstat-no, .fstat-no, .cbranch-no, .cbranch-no { background:#F6C6CE }
+/* light red */
+.low, .cline-no { background:#FCE1E5 }
+/* light green */
+.high, .cline-yes { background:rgb(230,245,208) }
+/* medium green */
+.cstat-yes { background:rgb(161,215,106) }
+/* dark green */
+.status-line.high, .high .cover-fill { background:rgb(77,146,33) }
+.high .chart { border:1px solid rgb(77,146,33) }
+/* dark yellow (gold) */
+.status-line.medium, .medium .cover-fill { background: #f9cd0b; }
+.medium .chart { border:1px solid #f9cd0b; }
+/* light yellow */
+.medium { background: #fff4c2; }
+
+.cstat-skip { background: #ddd; color: #111; }
+.fstat-skip { background: #ddd; color: #111 !important; }
+.cbranch-skip { background: #ddd !important; color: #111; }
+
+span.cline-neutral { background: #eaeaea; }
+
+.coverage-summary td.empty {
+    opacity: .5;
+    padding-top: 4px;
+    padding-bottom: 4px;
+    line-height: 1;
+    color: #888;
+}
+
+.cover-fill, .cover-empty {
+  display:inline-block;
+  height: 12px;
+}
+.chart {
+  line-height: 0;
+}
+.cover-empty {
+    background: white;
+}
+.cover-full {
+    border-right: none !important;
+}
+pre.prettyprint {
+    border: none !important;
+    padding: 0 !important;
+    margin: 0 !important;
+}
+.com { color: #999 !important; }
+.ignore-none { color: #999; font-weight: normal; }
+
+.wrapper {
+  min-height: 100%;
+  height: auto !important;
+  height: 100%;
+  margin: 0 auto -48px;
+}
+.footer, .push {
+  height: 48px;
+}

package/src/coverage/block-navigation.js

@@ -0,0 +1,87 @@
+/* eslint-disable */
+var jumpToCode = (function init() {
+    // Classes of code we would like to highlight in the file view
+    var missingCoverageClasses = ['.cbranch-no', '.cstat-no', '.fstat-no'];
+
+    // Elements to highlight in the file listing view
+    var fileListingElements = ['td.pct.low'];
+
+    // We don't want to select elements that are direct descendants of another match
+    var notSelector = ':not(' + missingCoverageClasses.join('):not(') + ') > '; // becomes `:not(a):not(b) > `
+
+    // Selector that finds elements on the page to which we can jump
+    var selector =
+        fileListingElements.join(', ') +
+        ', ' +
+        notSelector +
+        missingCoverageClasses.join(', ' + notSelector); // becomes `:not(a):not(b) > a, :not(a):not(b) > b`
+
+    // The NodeList of matching elements
+    var missingCoverageElements = document.querySelectorAll(selector);
+
+    var currentIndex;
+
+    function toggleClass(index) {
+        missingCoverageElements
+            .item(currentIndex)
+            .classList.remove('highlighted');
+        missingCoverageElements.item(index).classList.add('highlighted');
+    }
+
+    function makeCurrent(index) {
+        toggleClass(index);
+        currentIndex = index;
+        missingCoverageElements.item(index).scrollIntoView({
+            behavior: 'smooth',
+            block: 'center',
+            inline: 'center'
+        });
+    }
+
+    function goToPrevious() {
+        var nextIndex = 0;
+        if (typeof currentIndex !== 'number' || currentIndex === 0) {
+            nextIndex = missingCoverageElements.length - 1;
+        } else if (missingCoverageElements.length > 1) {
+            nextIndex = currentIndex - 1;
+        }
+
+        makeCurrent(nextIndex);
+    }
+
+    function goToNext() {
+        var nextIndex = 0;
+
+        if (
+            typeof currentIndex === 'number' &&
+            currentIndex < missingCoverageElements.length - 1
+        ) {
+            nextIndex = currentIndex + 1;
+        }
+
+        makeCurrent(nextIndex);
+    }
+
+    return function jump(event) {
+        if (
+            document.getElementById('fileSearch') === document.activeElement &&
+            document.activeElement != null
+        ) {
+            // if we're currently focused on the search input, we don't want to navigate
+            return;
+        }
+
+        switch (event.which) {
+            case 78: // n
+            case 74: // j
+                goToNext();
+                break;
+            case 66: // b
+            case 75: // k
+            case 80: // p
+                goToPrevious();
+                break;
+        }
+    };
+})();
+window.addEventListener('keydown', jumpToCode);