pr-validate

PR 验证技能

针对 PR 的验证，确保变更干净、聚焦且已准备就绪。

概述

通过检查隔离性、上游同步情况、范围限制和质量门禁，验证 PR 分支是否已准备好提交。

输入：分支名称（默认：当前分支）

使用时机：

• 运行 $pr-prep 之前
• $pr-implement 完成之后
• 怀疑范围蔓延时

---

工作流

1.  Branch Discovery     -> Identify branch and upstream
2.  Upstream Alignment   -> FIRST: Check rebase status (BLOCKING)
3.  CONTRIBUTING.md      -> Verify compliance (BLOCKING)
4.  Isolation Check      -> Single type, thematic files
5.  Scope Check          -> Verify changes match intended scope
6.  Quality Gate         -> Tests, linting (non-blocking)
7.  Report Generation    -> Summary with pass/fail

---

阶段 2：上游同步检查（阻塞性 — 首先检查）

# Fetch latest upstream
git fetch origin main

# How many commits behind?
BEHIND=$(git rev-list --count HEAD..origin/main)
echo "Behind upstream: $BEHIND commits"

检查项	通过标准
最小分歧	落后少于 20 个提交
无冲突	合并／变基可以成功

---

阶段 4：隔离检查（阻塞性）

# Commit type analysis
git log --oneline main..HEAD | sed 's/^[^ ]* //' | grep -oE '^[a-z]+(\([^)]+\))?:' | sort -u

# File theme analysis
git diff --name-only main..HEAD | cut -d'/' -f1-2 | sort -u

检查项	通过标准
单一提交类型	所有提交使用相同前缀
主题相关文件	所有变更文件都与 PR 范围相关
原子化范围	可以用一句话说明

---

阶段 5：范围检查

# Infer scope from commit messages
SCOPE=$(git log --format="%s" main..HEAD | grep -oE '\([^)]+\)' | sort -u | head -1)

# All files should be within expected scope
git diff --name-only main..HEAD | grep -v "$SCOPE"

---

生成报告

通过时的输出

PR Validation: PASS

Branch: feature/suggest-validation (5 commits)
Upstream: main (in sync)

Checks:
  [OK] Isolation: Single type (refactor)
  [OK] Upstream: 0 commits behind
  [OK] Scope: 100% in internal/suggest/
  [OK] Quality: Tests pass

Ready for $pr-prep

未通过时的输出

PR Validation: BLOCKED

Checks:
  [FAIL] Isolation: Mixed types (refactor, fix, docs)
  [WARN] Upstream: 15 commits behind

Resolutions:
1. ISOLATION: Split branch by commit type
   git checkout main && git checkout -b refactor/suggest
   git cherry-pick <refactor-commits>

Run $pr-validate again after resolution.

---

解决措施

混合提交类型

# Cherry-pick to clean branch
git checkout main
git checkout -b ${BRANCH}-clean
git cherry-pick <relevant-commits-only>

与上游分歧

# Rebase on latest upstream
git fetch origin main
git rebase origin/main

---

反模式

不要	应该这样做
分析过时的分支	先检查上游
跳过验证	在 $pr-prep 之前运行
忽视范围蔓延	提取无关变更
混合修复和重构	按类型拆分 PR

示例

提交前验证 PR

用户说：“验证此 PR 分支的隔离性，并检查是否存在范围蔓延。”

执行内容：

1. 检查上游同步情况和分支是否为最新。
2. 检测范围蔓延和无关的文件变更。
3. 输出补救步骤以及通过／未通过状态。

准备前的门禁检查

用户说：“在我运行 $pr-prep 之前执行 PR 验证。”

执行内容：

1. 执行隔离性和范围检查。
2. 确认是否满足质量门禁要求。
3. 给出是否继续的建议。

故障排除

问题	原因	解决方案
验证报告分支过时	上游已有新进展	从上游执行变基／合并，然后重新运行
检测到范围蔓延	存在额外文件或目标混杂	将无关变更拆分到后续 PR
同步检查未通过	分支与目标预期不一致	协调基分支和验收标准
输出不清晰	发现项未排序	按阻塞性与非阻塞性严重程度排序

参考文档

• references/pr-validate.feature — 可执行规范：隔离性、上游同步、范围限制和质量门禁检查 → 提交准备就绪判定（soc-qk4b）