SuperAPI AI 工具集

git-detect-breaking-changes

编程与开发

查看项目

更新于 11-02 04:45

技能介绍

用途 该技能面向 CDS 仓库的提交审查,检查最近指定数量的提交是否在 CDS 公共 API 表面引入破坏性变更。分析范围仅限 packages/web、packages/mobile、packages/common 三个包。

主要能力

  1. 解析公共 API 边界:每个包均为 ESM,先查看 package.json 的 exports 映射确定公共入口,再沿入口 index.ts barrel 文件追踪重导出模块;凡消费者可通过已发布入口导入的组件、函数、hook、常量、类型、接口、枚举,均纳入分析。
  2. 提交检索与差异检查:对每个包使用 git log --oneline -$ARGUMENTS -- <package-path> 定位相关提交,使用 git diff HEAD~$ARGUMENTS..HEAD -- <package-path> 与 git show <sha> 查看实际改动。仅保留可从公共导出路径到达的文件。
  3. 六类破坏性变更判定:
    • 移除:已导出符号被删除或不再导出;
    • API 变更:props 或函数签名变化导致既有消费者失效,如新增必填 prop、prop 重命名、可选值收窄、参数删除/重排/变为必填、hook 返回结构变化、默认值移除或改变行为;
    • 类型定义变更:导出类型、接口或枚举改动导致消费者 TypeScript 编译失败;
    • 视觉/布局变更:样式、间距、尺寸或视觉输出变化影响消费者布局外观;
    • DOM/元素结构变更(仅限 web 包):渲染元素树变化可能破坏消费者 CSS 选择器或 DOM 查询,如增删包裹元素、标签名变化、嵌套顺序变化、类名或 data 属性移除重命名、role 或 aria-* 移除变更;
    • 行为变更:签名不变但运行时行为改变,如事件回调约定、受控/非受控行为、动画过渡、焦点管理、无障碍(如键盘导航)行为变化。
  4. 报告输出:按包组织,包内按类别分组,每项包含实体、类别、说明、文件、提交 SHA;省略无发现的类别与包。随后提供汇总,包括各类别破坏性变更总数、最可能造成广泛破坏的高风险项,以及消费者需要的迁移说明。
  5. 分析准则:要求彻底且精确,不把不影响公共 API 的内部重构计为破坏性变更;对导出归属存疑时从 package.json exports 逐层回溯;视觉变更尽量记录前后值;DOM 变化需描述到消费者能据此更新选择器;不推测,只报告 diff 中可验证的改动。

使用方式 该技能通过参数 $ARGUMENTS 指定要回看的提交数量,并在 CDS 仓库环境中运行;具体调用入口与安装方式暂未提供。

适用场景 适用于 CDS 仓库发版前或合并前审查,评估近期提交对 web、mobile、common 三个包公共 API 的影响,辅助判断版本升级所需迁移工作。

限制 仅分析上述三个包且仅关注公共 API 可达内容;不覆盖内部实现重构;不推测无法从 diff 验证的变更;具体运行命令、依赖与集成方式暂未提供。