SuperAPI AI 工具集

git.detect-breaking-changes

编程与开发

查看项目

更新于 10-15 20:14

技能介绍

用途:分析最近 N 次提交中 CDS 公共 API 的破坏性变更,判断近期改动是否会导致下游消费者代码失效。

范围:仅分析 packages/web/、packages/mobile/、packages/common/ 三个包。

公共 API 判定:各包为纯 ESM,需查看 package.json 的 exports 映射确定公开入口,再沿入口 index.ts barrel 文件追踪重导出模块;凡消费者可通过已发布入口导入的符号(组件、函数、hook、常量、类型、接口、枚举)均属公共 API。

分析方式:对每个包使用 git log --oneline -$ARGUMENTS -- <package-path> 定位相关提交,用 git diff HEAD~$ARGUMENTS..HEAD -- <package-path> 和 git show <sha> 查看实际改动;先判断文件是否可从公开导出路径到达,不可达则跳过。

破坏性变更类别:1) 移除:已导出符号被删除或不再导出;2) API 变更:函数、hook 或组件的调用签名变化,如新增必填 prop、重命名 prop、收窄取值、参数删除或重排、hook 返回结构变化、默认值移除或改变;3) 类型定义变更:公开类型、接口或枚举修改导致消费者 TypeScript 编译失败;4) 视觉/布局变更:样式、间距、尺寸或视觉输出变化影响布局外观;5) DOM/元素结构变更(仅 web 包):渲染元素树变化可能破坏消费者 CSS 选择器或 DOM 查询;6) 行为变更:签名不变但运行时行为改变。

输出格式:按包组织,包内按类别分组,每条包含 Entity、Category、Description、File、Commit;空类别省略,无破坏性变更的包省略。最后给出汇总:各类别总数、最高风险变更、迁移说明。

限制:需精确,不标记不影响公共 API 的内部重构;不确定是否公开导出时沿导出链核实;视觉变更尽量给出前后值;DOM 变更需描述到消费者可更新选择器的程度;不得臆测,只报告可从 diff 验证的改动。