bumpgen 自动检测并更新npm依赖版本的智能Agent工具

📝 概述

bumpgen 能帮你升级 TypeScript / TSX 项目的依赖项，并在出现破坏性变更时自动修改代码。

这是一个常见的场景：

你：“我应该升级到 x 的最新版本，它有很棒的新功能和显著的性能提升。”

你（5分钟后）：算了，这搞坏了一堆东西。

那就用 bumpgen 吧！

它是如何工作的？

• bumpgen 会构建你的项目，以了解升级依赖时哪些地方被破坏了。
• 接着，bumpgen 使用 ts-morph 从你的代码生成抽象语法树，以理解语句之间的关系。
• 它还利用 AST 获取外部方法的类型定义，以了解如何使用新版本的包。
• 然后，bumpgen 创建一个计划图（一个有向无环图，DAG），按正确顺序执行任务，以处理变更的传播（参考：arxiv 2309.12499）。

[!NOTE]
bumpgen 目前仅支持 TypeScript 和 TSX，但我们正在努力添加对其他强类型语言的支持。请在我们关于 Java、Golang、C# 和 Python 的公开议题上点击表情按钮来请求支持。

🚀 快速开始

要开始使用，你需要一个 OpenAI API 密钥。目前唯一支持的模型是 OpenAI 的 gpt-4-turbo-preview，不过我们计划很快支持更多模型。

然后，运行 bumpgen：

> export LLM_API_KEY="<openai-api-key>"
> cd ~/my-repository
> npm install -g bumpgen
> bumpgen @tanstack/react-query 5.28.14

其中 @tanstack/react-query 是你想要升级的包，5.28.14 是你想要升级到的版本。

你也可以不带参数运行 bumpgen，然后从菜单中选择要升级的包。使用 bumpgen --help 查看完整的选项列表。

GitHub Action

我们创建了一个 GitHub Action 来运行 bumpgen。其预期用途是在 dependabot 或 renovatebot 的 PR 上触发——如果检测到破坏性变更，bumpgen 会向该 PR 分支提交更改。

[!NOTE]
该 Action 会将更改提交到触发它的分支。如果你希望这些提交能触发其他 CI 工作流，你需要使用 GitHub 的个人访问令牌。

示例工作流

name: "Bumpgen"

on:
  pull_request:
    types:
      - opened

permissions:
  pull-requests: read
  contents: write

jobs:
  main:
    name: Run Bumpgen
    runs-on: ubuntu-latest
    if: ${{ github.event.pull_request.user.login == 'dependabot[bot]'}} # 对于 renovate 的 PR，使用 'renovate[bot]'
    steps:
      - uses: actions/checkout@v4
      - name: Setup # 在运行 bumpgen action 之前，检出并设置你的项目
        uses: ./tooling/github/setup
      - name: Bumpgen
        uses: xeol-io/bumpgen@v0.0.1
        with:
          path: "./packages/bumpgen-core/" # 你的项目 package.json 文件的位置
          llm_key: ${{ secrets.LLM_API_KEY }}
          github_token: ${{ secrets.GITHUB_TOKEN }}

[!NOTE]
如果你想成为首批试用 bumpgen GitHub App 以替代 dependabot + renovatebot 的用户，请在此注册。

局限性

你需要了解一些局限性。

• bumpgen 依赖构建错误来确定需要修复的内容。如果问题是由行为变更引起的，bumpgen 将无法检测到。
• bumpgen 无法同时处理多个包。对于需要同时更新对等依赖才能工作的包（例如 @octokit/core 和 @octokit/plugin-retry），它将无法升级。
• bumpgen 不擅长处理像 vue 这样非常庞大的框架。这类升级（特别是 vue 2 -> 3）即使对人类来说也可能很艰巨。

🏙️ 架构

 > bumpgen @tanstack/react-query 5.28.14
       │
┌┬─────▼──────────────────────────────────────────────────────────────────────┐
││ CLI                                                                        │
└┴─────┬──▲───────────────────────────────────────────────────────────────────┘
       │  │
┌┬─────▼──┴───────────────────────────────────────────────────────────────────┐
││ Core (Codeplan)                                                            │
││                                                                            │
││ ┌───────────────────────────────────┐ ┌──────────────────────────────────┐ │
││ │ Plan Graph                        │ │ Abstract Syntax Tree             │ │
││ │                                   │ │                                  │ │
││ │                                   │ │                                  │ │
││ │               ┌─┐                 │ │                  ┌─┐             │ │
││ │            ┌──┴─┘                 │ │               ┌──┴─┴──┐          │ │
││ │            │                      │ │               │       │          │ │
││ │           ┌▼┐                  ┌──┼─┼──┐           ┌▼┐     ┌▼┐         │ │
││ │           └─┴──┐               │  │ │  │        ┌──┴─┴──┐  └─┘         │ │
││ │                │                  │ │  ▼        │       │              │ │
││ │               ┌▼┐              ▲  │ │          ┌▼┐     ┌▼┐             │ │
││ │               └─┴──┐           │  │ │  │       └─┘  ┌──┴─┴──┐          │ │
││ │                    │           └──┼─┼──┘            │       │          │ │
││ │                   ┌▼┐             │ │              ┌▼┐     ┌▼┐         │ │
││ │                   └─┘             │ │              └─┘     └─┘         │ │
││ │                                   │ │                                  │ │
││ │                                   │ │                                  │ │
││ │                                   │ │                                  │ │
││ │                                   │ │                                  │ │
││ └───────────────────────────────────┘ └──────────────────────────────────┘ │
││                                                                            │
└┴─────┬──▲───────────────────────────────────────────────────────────────────┘
       │  │
┌┬─────▼──┴───────────────────────────┐  ┌┬───────────────────────────────────┐
││ Prompt Context                     │  ││ LLM                               │
││                                    │  ││                                   │
││ - plan graph                       │  ││ GPT4-Turbo, Claude 3, BYOM        │
││ - errors                           ├──►│                                   │
││ - code                             │  ││                                   │
││                                    ◄──┼│                                   │
││                                    │  ││                                   │
││                                    │  ││                                   │
││                                    │  ││                                   │
└┴────────────────────────────────────┘  └┴───────────────────────────────────┘

抽象语法树

AST 由 ts-morph 生成。这个 AST 让 bumpgen 能够理解代码库中节点之间的关系。

计划图

计划图是微软 codeplan 论文中详述的一个概念。计划图使 bumpgen 不仅能修复某个点的问题，还能修复由修复本身引起的二阶破坏性变更。简而言之，它允许 bumpgen 将修复传播到代码库的其余部分。

提示上下文

我们将计划图、错误信息以及包含破坏性变更的实际文件作为上下文传递给 LLM，以最大化其修复问题的能力。

大语言模型

目前我们仅支持 gpt-4-turbo-preview。

⏱️ 基准测试

bumpgen + GPT-4 Turbo         ██████████░░░░░░░░░░░   45% (67 tasks)

我们使用 GPT-4 Turbo 版本的 bumpgen 对一个包含破坏性变更的版本升级测试套件进行了基准测试。你可以在此查看评估结果这里。

🎁 贡献

欢迎贡献！要设置开发环境，请参阅开发指南。

路线图

• [x] codeplan
• [x] Typescript/TSX 支持
• [ ] bumpgen GitHub 应用
• [ ] 不同包版本的嵌入
• [ ] 使用测试运行器作为验证工具
• [ ] C# 支持
• [ ] Java 支持
• [ ] Go 支持

Join 加入我们的 Discord 社区，参与贡献、了解更多信息并提出问题！