gitnexus-pr-review

使用 GitNexus 进行 PR 审查

何时使用

• “审查这个 PR”
• “PR #42 改了什么？”
• “这个可以安全合并吗？”
• “这个 PR 的影响范围有多大？”
• “这个 PR 是否缺少测试？”
• 在合并前审查他人的代码更改

工作流

1. gh pr diff <number>                                    → Get the raw diff
2. detect_changes({scope: "compare", base_ref: "main"})  → Map diff to affected flows
3. For each changed symbol:
   impact({target: "<symbol>", direction: "upstream"})    → Blast radius per change
4. context({name: "<key symbol>"})               → Understand callers/callees
5. READ gitnexus://repo/{name}/processes                   → Check affected execution flows
6. Summarize findings with risk assessment

如果出现 “Index is stale” → 在审查前先在终端运行 node .gitnexus/run.cjs analyze。

检查清单

- [ ] Fetch PR diff (gh pr diff or git diff base...head)
- [ ] detect_changes to map changes to affected execution flows
- [ ] impact on each non-trivial changed symbol
- [ ] Review d=1 items (WILL BREAK) — are callers updated?
- [ ] context on key changed symbols to understand full picture
- [ ] Check if affected processes have test coverage
- [ ] Assess overall risk level
- [ ] Write review summary with findings

审查维度

维度	GitNexus 如何帮助
正确性	context 显示调用方——它们是否都与该更改兼容？
影响范围	impact 显示 d=1/d=2/d=3 的依赖项——是否有遗漏？
完整性	detect_changes 显示所有受影响的流程——它们是否都已处理？
测试覆盖率	impact({includeTests: true}) 显示哪些测试涉及更改的代码
破坏性更改	PR 中未更新的 d=1 上游项 = 潜在破坏

风险评估

信号	风险
更改涉及 <3 个符号，0-1 个流程	低
更改涉及 3-10 个符号，2-5 个流程	中
更改涉及 >10 个符号或许多流程	高
更改涉及认证、支付或数据完整性代码	严重
PR diff 之外存在 d=1 调用方	潜在破坏——标记出来

工具

detect_changes — 将 PR diff 映射到受影响的执行流程：

detect_changes({scope: "compare", base_ref: "main"})

→ Changed: 8 symbols in 4 files
→ Affected processes: CheckoutFlow, RefundFlow, WebhookHandler
→ Risk: MEDIUM

impact — 每个更改符号的影响范围：

impact({target: "validatePayment", direction: "upstream"})

→ d=1 (WILL BREAK):
  - processCheckout (src/checkout.ts:42) [CALLS, 100%]
  - webhookHandler (src/webhooks.ts:15) [CALLS, 100%]

→ d=2 (LIKELY AFFECTED):
  - checkoutRouter (src/routes/checkout.ts:22) [CALLS, 95%]

带测试的 impact — 检查测试覆盖率：

impact({target: "validatePayment", direction: "upstream", includeTests: true})

→ Tests that cover this symbol:
  - validatePayment.test.ts [direct]
  - checkout.integration.test.ts [via processCheckout]

context — 理解更改符号的作用：

context({name: "validatePayment"})

→ Incoming calls: processCheckout, webhookHandler
→ Outgoing calls: verifyCard, fetchRates
→ Processes: CheckoutFlow (step 3/7), RefundFlow (step 1/5)

示例：“审查 PR #42”

1. gh pr diff 42 > /tmp/pr42.diff
   → 4 files changed: payments.ts, checkout.ts, types.ts, utils.ts

2. detect_changes({scope: "compare", base_ref: "main"})
   → Changed symbols: validatePayment, PaymentInput, formatAmount
   → Affected processes: CheckoutFlow, RefundFlow
   → Risk: MEDIUM

3. impact({target: "validatePayment", direction: "upstream"})
   → d=1: processCheckout, webhookHandler (WILL BREAK)
   → webhookHandler is NOT in the PR diff — potential breakage!

4. impact({target: "PaymentInput", direction: "upstream"})
   → d=1: validatePayment (in PR), createPayment (NOT in PR)
   → createPayment uses the old PaymentInput shape — breaking change!

5. context({name: "formatAmount"})
   → Called by 12 functions — but change is backwards-compatible (added optional param)

6. Review summary:
   - MEDIUM risk — 3 changed symbols affect 2 execution flows
   - BUG: webhookHandler calls validatePayment but isn't updated for new signature
   - BUG: createPayment depends on PaymentInput type which changed
   - OK: formatAmount change is backwards-compatible
   - Tests: checkout.test.ts covers processCheckout path, but no webhook test

审查输出格式

将你的审查组织为：

## PR Review: <title>

**Risk: LOW / MEDIUM / HIGH / CRITICAL**

### Changes Summary
- <N> symbols changed across <M> files
- <P> execution flows affected

### Findings
1. **[severity]** Description of finding
   - Evidence from GitNexus tools
   - Affected callers/flows

### Missing Coverage
- Callers not updated in PR: ...
- Untested flows: ...

### Recommendation
APPROVE / REQUEST CHANGES / NEEDS DISCUSSION