bumpgen

bumpgen is an AI agent specifically designed to upgrade npm packages and automatically modify TypeScript/TSX code when upgrades cause code breakage. It is intended to solve a common problem developers encounter when manually upgrading dependencies: after upgrading, the code has a large number of errors, and fixing them is time-consuming and laborious.

Purpose bumpgen's main purpose is to automate the npm package upgrade process. When developers want to upgrade a dependency package to a new version, bumpgen can automatically complete the upgrade and detect and fix code breakage caused by the upgrade.

Main capabilities

• Automatically upgrade npm packages: you can specify the package name and target version, or run it without arguments and select the package to upgrade from a menu.
• Automatically fix breaking changes: by building the project, it learns what went wrong after the dependency upgrade and automatically modifies the code.
• Understand code structure: use ts-morph to generate an abstract syntax tree (AST), understand the relationships between statements, and obtain type definitions of external methods to understand how to use the new version of the package.
• Plan graph execution: create a plan graph DAG to execute operations in the correct order and handle propagating changes (refer to arXiv 2309.12499).
• GitHub Action integration: you can create a GitHub Action that triggers on dependabot or renovatebot PRs and automatically commits to the PR branch when breaking changes are detected.

How to use

1. Requires an OpenAI API key, and currently only supports the gpt-4-turbo-preview model.
2. Run the command to upgrade the specified package, for example:bumpgen @tanstack/react-query 5.28.14, where @tanstack/react-query is the package to upgrade, and5.28.14 is the target version.
3. You can also run it without arguments bumpgen, and select the package to upgrade from the menu. Use bumpgen --help View the full options.
4. When using GitHub Action, trigger on dependabot or renovatebot PRs. The Action commits changes to the triggering branch. If you want these commits to trigger other CI workflows, you need to use a GitHub Personal Access Token.

Use cases

• When you need to upgrade npm dependencies in a TypeScript/TSX project but are worried about breaking the code.
• Work with dependabot or renovatebot to automatically fix breaking changes in dependency upgrade PRs.

Limitations

• Currently only TypeScript and TSX are supported; other strongly typed languages (Java, Golang, C#, Python) are planned.
• Only the gpt-4-turbo-preview model is supported.
• Uses build errors to determine what needs to be fixed. If the issue is caused by behavior changes, bumpgen cannot detect it.
• Cannot handle multiple packages at the same time. For packages that require updating peer dependencies together (such as @octokit/core and @octokit/plugin-retry), the upgrade will fail.
• Does not work well for large frameworks (such as Vue), especially Vue 2 to 3 upgrades, which are difficult even for humans.

Architecture

• The AST is generated by ts-morph, enabling bumpgen to understand the relationships between nodes in the codebase.
• The plan graph concept comes from Microsoft's codeplan. The plan graph not only fixes the problem at a certain point, but also fixes secondary breaking changes caused by the fix itself, thereby propagating the fix throughout the codebase.
• The plan graph, errors, and the actual files containing breaking changes are passed as context to the LLM to maximize repair capabilities.

Other information bumpgen provides an evaluation benchmark, using GPT-4 Turbo to test a series of version upgrades containing breaking changes. The project welcomes contributions and has development setup guidelines. Future plans include TypeScript/TSX support, bumpgen GitHub App, embeddings for different package versions, and using a test runner as an oracle.