Frontend Code Review

Variants

When NOT to Use

• 服务端代码
• 文档评审
• 安全专项评审

Step 0: Init (Fail-closed)

Execute: bash scripts/emit-review-gate.sh PENDING

写入初始状态到 ~/.pipeline-ai-workflow/frontend-code-review/{branch_name}/state.json：

{
  "_meta": {
    "created_at": "<ISO timestamp>",
    "updated_at": "<ISO timestamp>",
    "namespace": "frontend-code-review/{branch_name}"
  },
  "status": "running",
  "data": {
    "review_mode": "dual",
    "aggregate_gate": {
      "executed": false,
      "gate": "PENDING"
    },
    "iteration": 0,
    "codex_thread_id": null,
    "secondary_status": "pending"
  }
}

若状态文件已存在且 status = running，输出警告并询问是否恢复上次会话。

Fail-closed 语义：进程在 Step 4.5 前崩溃时，gate 保持 PENDING 阻断合并。

Step 1: Diff Analysis

根据变体获取 diff：

分析 diff，输出结构化变更信息：

统计变更概况（所有变体）：

• 变更文件数、新增/删除行数
• 文件类型分布：源代码、测试、配置、文档、依赖、构建/CI

分类变更类型（所有变体）：

安全扫描（Full / Branch）：

输出两份变量：

DIFF_STAT（结构化摘要，供 Codex prompt 注入和安全聚合）：

{
  "summary": { "files_changed": 12, "insertions": 345, "deletions": 128, "risk_level": "medium" },
  "file_categories": {
    "source_code": ["src/components/Button.tsx"],
    "tests": [],
    "config": [],
    "dependencies": []
  },
  "change_types": { "feat": { "files": ["..."], "description": "..." } },
  "security_findings": [
    { "severity": "warning", "file": "src/api/client.ts", "line": 9, "finding": "..." }
  ]
}

RAW_DIFF（完整 git diff 原文，供 Step 3 副审使用）：直接保存上方 diff 命令的完整文本输出，不做任何裁剪或结构化处理。

Step 2: Frontend Static Checks (Full / Branch only)

探测 lint / bundle 命令（读取 package.json）：

1. 读取 package.json scripts 字段，按优先级匹配：
• lint 命令：lint → lint:fix → eslint → eslint src
• bundle 检查：size → bundlesize → size-limit
2. 检查 bundle 配置文件是否存在：.bundlesizerc / .size-limit.json / size-limit.config.js
3. 检测前端框架：dependencies 中匹配 react/vue/svelte/solid，存为 FRAMEWORK

执行检查：

# ESLint（含 jsx-a11y plugin，如已安装）
{LINT_COMMAND}

# Bundle size（仅当配置文件存在时执行，否则静默跳过）
{BUNDLE_SIZE_COMMAND}

结果存为 LOCAL_CHECKS，注入 Step 3 Codex prompt。

Step 3: Dual Review (Parallel)

Case A: First review（无 --continue）

单条消息并行启动两个 reviewer：

1. Codex MCP（主审，阻塞）

参考 references/retry-executor.md 执行重试包裹：

• action_type: api_call，retry_policy: default（3 次，指数退避），timeout_seconds: 120
• on_failure: return_error（降级模式，不阻塞）

调用 mcp__codex__codex，按变体选择 prompt 模板：

• Fast → references/codex-prompt-fast.md
• Full → references/codex-prompt-full.md
• Branch → references/codex-prompt-branch.md

注入变量：

• CHANGED_FILES ← DIFF_STAT.file_categories
• DIFF_STAT ← Step 1 summary
• LOCAL_CHECKS ← Step 2 lint + bundle 结果（Full/Branch only）
• FRAMEWORK ← 从 package.json 检测
• 若 security_findings 非空，追加到 prompt Focus Area

保存返回的 threadId，更新状态文件：

{ "data": { "codex_thread_id": "<threadId>", "iteration": 1 } }

2. Reviewer Framework（副审，非阻塞后台）

参考 references/reviewer-framework.md 执行：

target_content: {RAW_DIFF}
review_dimensions: ["typescript", "async-error", "code-structure", "naming", "component-design", "dry-reuse", "state-management", "security", "imports", "comments", "accessibility", "hooks-correctness", "memory-leak", "null-safety", "css-quality", "async-race"]
severity_threshold: minor
output_format: json

Fallback 级联：

1. 按 references/reviewer-framework.md 执行（默认）
2. pr-review-toolkit:code-reviewer（framework 执行失败时）
3. Codex 单审降级模式（两者均不可用时）

Case B: Loop review（有 --continue）

• Codex：通过重试包裹调用 mcp__codex__codex-reply(threadId)，使用 references/review-common.md § Re-review Prompt Template
• Reviewer Framework：重新调用（fresh context），无跳过例外

Step 3.5: Await and Reconcile

Codex 为阻塞主审，reviewer-framework 后台非阻塞运行：

Step 4: Three-Source Aggregation

来源：Codex + reviewer-framework + Step 1 安全发现。

详细聚合规则（severity 映射、去重算法、降级矩阵）见 references/review-common.md § Three-Source Aggregation。

1. 归一化 所有发现到统一格式：[severity] file:line — description → fix [source: ...]
2. 去重：key = file + canonical_issue_text（行号 ±5 容差），保留最高严重级别
3. 标注 source：codex | framework | diff-analyzer | both | all
4. 排序：P0 → P1 → P2 → Nit
5. 门控判断：任意 P0/P1 → BLOCKED；否则 → READY

输出示例：

⛔ P0 — Must Fix (Merge Blocked)

🔴 P1 — Should Fix

🟡 P2 — Nice to Fix

💬 Nit

Step 4.5: Persist Gate State

Execute: bash scripts/emit-review-gate.sh READY or bash scripts/emit-review-gate.sh BLOCKED

更新状态文件 ~/.pipeline-ai-workflow/frontend-code-review/{branch_name}/state.json：

{
  "data": {
    "aggregate_gate": {
      "executed": true,
      "gate": "READY | BLOCKED",
      "source": "codex+framework | codex-only | framework-only",
      "findings_count": { "P0": 0, "P1": 0, "P2": 2, "Nit": 1 }
    },
    "iteration": 1
  }
}

输出 sentinel：

• ✅ Ready — READY（无 P0/P1）
• ⛔ Blocked — BLOCKED（有 P0/P1）

Review Loop

⚠️ BLOCKED → fix → re-review → ... → ✅ READY ⚠️

BLOCKED → 修复 P0/P1 → /fe-review-fast --continue → 重复直到 READY。

READY + P2/Nit → 批量修复 → 1 次 Codex --continue 验证 → 评估（见 references/review-common.md § P2/Nit Post-Ready Sweep）。

Loop 终止规则见 references/review-common.md § Loop Termination Rules。

Pre-precommit Checkpoint

precommit 前调和待定副审结果：

Verification

• [ ] 每个发现标注严重级别（P0/P1/P2/Nit）和 source
• [ ] Gate sentinel 清晰输出（✅ Ready / ⛔ Blocked）
• [ ] 发现包含：file:line、描述、修复建议
• [ ] Codex 独立进行了项目研究（读取实际文件内容）
• [ ] Framework 从 package.json 自动检测并注入 prompt
• [ ] LOCAL_CHECKS（lint + bundle）注入 Codex prompt（Full/Branch only）
• [ ] diff-analyzer 安全发现合并到聚合输出
• [ ] 状态文件持久化了 gate 状态和 iteration 计数
• [ ] Loop 最大迭代（5 轮）已执行；per-issue 3 轮停滞检测已激活
• [ ] 副审迟到 P0/P1 在 precommit 前重开 fix loop
• [ ] a11y 维度已纳入 reviewer-framework 和 Codex Full/Branch prompt
• [ ] hooks-correctness 维度已纳入（无限循环 P0、unmount setState / 闭包陷阱 P1）
• [ ] memory-leak 维度已纳入（addEventListener / setInterval 未清理 P1）
• [ ] null-safety 维度已纳入（深层属性访问无 ?. P1）
• [ ] css-quality 维度已纳入（!important 滥用、硬编码颜色、z-index 魔法值 P2）
• [ ] async-race 维度已纳入（竞态条件、state 直接 mutation P1）

References

• Shared definitions & aggregation rules: references/review-common.md
• Retry logic: references/retry-executor.md
• Reviewer framework: references/reviewer-framework.md
• Fast prompt: references/codex-prompt-fast.md
• Full prompt: references/codex-prompt-full.md
• Branch prompt: references/codex-prompt-branch.md