check-api-branch

name	check-api-branch
description	合并 master 前检查 swagger-repo.json 是否残留 feat 分支，半自动逐条切回并重跑 gen:api。**触发场景**：准备合并到 master 之前（由 git-ship skill 自动调用）/ 修改过 swagger-repo.json 的 branch 字段 / 拉到陌生分支后想确认 API 类型来源 / 用户输入 /check-api-branch。
argument-hint	["可选 flag，如 --strict --target-branch main"]
allowed-tools	Bash(git *), Bash(node *), Bash(npm *), Read

check-api-branch

合并 master 前检查 swagger-repo.json 是否还残留 feat 分支，半自动逐条切回并重跑 gen:api。

何时使用

• 准备 git-ship 合并到 master 之前
• 修改过 swagger-repo.json 的某条 branch 后
• 拉到陌生分支后想确认 API 类型来源

参数

$ARGUMENTS — 可选，传给底层脚本（如 --strict、--target-branch main）

步骤

1. 确认目标分支是 master

如果当前 PR/MR 的目标分支不是 master（比如要合到一个长期分支），跳过本检查，提示用户："本次合并目标非 master，跳过 swagger 分支检查。"

# 当前所在分支（参考，最终目标分支可能不同）
git branch --show-current
# 当前 upstream（如果设置了）
git rev-parse --abbrev-ref HEAD@{upstream} 2>/dev/null || echo "(no upstream)"

如果用户的合并目标不是 master/main，提示并返回，不跑后续步骤。

2. 跑半自动检查

node ./scripts/check-swagger-branch.mjs --fix-interactive $ARGUMENTS

脚本会：

1. 列出所有 branch !== 'master' 的条目
2. 逐条问"切回 master？(y/N)"，用户决策
3. 至少有 1 条被切回 -> 写回 swagger-repo.json -> 自动跑 npm run gen:api
4. 全部保留 -> 不改 JSON、不跑 gen:api

注意：feat 分支可能确实未合到 master（后端在做的功能），让用户按实际情况决策。禁止强制切回。

3. 审视生成代码差异

如果脚本跑了 gen:api，立即查看 src/__generated__/（或 src/api/__generated__/ 等本项目实际目录）的 diff：

git status --short src/__generated__/ src/api/__generated__/ 2>/dev/null
git diff src/__generated__/ src/api/__generated__/ 2>/dev/null | head -200

提示用户：

• API 类型变化是否影响业务代码（field 名变了 / 类型变了 / 接口删了）
• 必要时让用户改一遍业务代码后再 commit

4. 输出报告

## check-api-branch 完成
| 检查项 | 状态 |
|--------|------|
| 目标分支 | master |
| 非 master 条目 | <数量> |
| 切回 | <数量> |
| gen:api | <成功 / 跳过> |
| __generated__ diff | <有 / 无> |

下一步建议：<根据 diff 提示用户>

已知边界 / escape hatch

• swagger-repo.json 不在根目录：用 $ARGUMENTS 加 --config <path>
• 目标分支不叫 master：用 $ARGUMENTS 加 --target-branch main
• gen 命令不叫 npm run gen:api：用 $ARGUMENTS 加 --gen-cmd "<custom>"
• swagger-repo.json 不存在：脚本会友好退出（exit 0），告知该项目不需要本检查

规则

• 禁止一刀切（脚本本身已 enforce 逐条询问）
• 禁止合并目标不是 master 时跑（步骤 1 拦截）
• gen:api 失败 -> 不要重试，告诉用户手动排查（可能是网络 / SSH / 后端权限）