【ITニュース解説】I built a tool that tells you which lines an npm upgrade will break

システム開発の現場では、プロジェクトが「Express」や「axios」といった多くの外部ライブラリ、つまり「依存関係」の上に成り立っていることが一般的だ。これらの依存関係は常に進化し、セキュリティ修正や新機能追加のために新しいバージョンがリリースされる。プロジェクトの品質と安全性を保つためには、依存関係を最新の状態に保つ「アップグレード」が非常に重要だが、この作業は多くの開発者にとって頭の痛い問題だった。

なぜなら、新しいバージョンに更新した際に、既存のコードが正しく動作しなくなる「破壊的な変更」が含まれている可能性があるからだ。ライブラリの「変更履歴」を読んでも、ライブラリそのものの変更は分かるが、自分の書いたコードのどの行に影響があるのか、具体的にどこを修正すれば良いのかまでは教えてくれない。結局のところ、実際にバージョンを上げてビルドを実行し、エラーが出たら修正するという試行錯誤のプロセスが必要となり、この手間がアップグレード作業を後回しにする大きな原因となっていた。

このような課題を解決するために開発されたのが、「bumpscan（バンプスキャン）」というコマンドラインインターフェース（CLI）ツールだ。bumpscanは、依存関係をアップグレードする前に、あなたのコードのどの行が新しいバージョンによって壊れる可能性があるかを事前に教えてくれる。これにより、開発者は未知の不安を抱えることなく、安心してアップグレード作業に取り組むことができるようになる。

bumpscanの使い方は非常にシンプルだ。例えば、「Express」ライブラリをバージョン4から5にアップグレードしたい場合、プロジェクトのディレクトリでnpx bumpscan express@5とコマンドを実行する。すると、bumpscanはアップグレードによる変更点を詳細に分析し、レポートとして出力する。

出力の例を見ると、express 4.22.3 → 5.2.1のようにバージョンアップの前後が表示され、types from @types/express@4.17.25 → @types/express@5.0.6として、そのライブラリの型定義ファイルもアップグレードされることが示される。そして最も重要なのは、「Breaks your code (3)」のように、実際にコードが壊れる可能性のある箇所と、その理由を具体的に表示してくれる点だ。例えば、「あなたのプロジェクト全体でNode.js 18.0.0以降が必要になります」というシステム要件の変更や、「Request.paramメソッドが削除されました」といった特定のAPIの変更が挙げられる。さらに、src/server.ts:8:14 const id = req.param("id");のように、具体的なファイル名、行番号、該当するコードまで示されるため、開発者はすぐに修正箇所を特定できる。もし適切な修正案があれば、「💡 fix: maybe use sendFile」のようにヒントも提供される。bumpscanは、アップグレードによる多くの変更点の中で、実際に自分のコードに影響する「重要な数行」を見つけ出すことに特化している。

bumpscanは、AIやサーバーとの通信を一切使わず、すべてあなたのローカルマシン上で動作する。その動作原理は三つのステップで構成されている。

第一に、現在使われているバージョンと、あなたがアップグレードしたい新しいバージョンの両方をnpmからダウンロードする。これは、package.jsonファイルから現在のバージョンを読み取り、指定された新しいバージョンを解決して取得する。

第二に、ダウンロードした新旧両バージョンの「公開API」を比較する。JavaScriptやTypeScriptのプロジェクトで使われる「型定義ファイル（.d.ts）」を読み込み、ライブラリが公開しているすべての関数やプロパティの情報をリスト化する。そして、この二つのリストを比較し、何が削除、リネーム、必須化、変更されたかを特定する。

第三に、あなたのプロジェクトのソースコードをスキャンする。bumpscanは、インポート文、require()関数、メソッドチェーン、コールバック関数の引数など、あなたがパッケージを使っているあらゆる箇所を解析する。そして、特定されたAPIの変更点と照らし合わせ、実際にあなたのコードが影響を受ける箇所だけをピックアップして表示する。

また、bumpscanは型定義ファイルには直接書かれていないが、ビルドを壊す可能性のある変更点もチェックする。例えば、パッケージがこれまでのCommonJS形式からESM（ECMAScript Modules）形式に完全に移行したためにrequire()関数が動作しなくなるケースや、パッケージが要求するNode.jsの最小バージョンが引き上げられたケースなどだ。これらは、実際にプロジェクトのビルドが失敗する原因となることが多いため、非常に有用なチェック項目である。

bumpscanの開発過程では、いくつかの興味深い課題に直面し、それを乗り越えた。例えば、最初は「削除された」と報告されたAPIが、実際には内部的な構造やインターフェースの継承関係が変更され、「移動」しただけであったという誤検出が多かった。bumpscanは、これらの継承関係を深く追跡することで、誤検出を大幅に減らした。また、expressのようなライブラリでは、主要なAPIの型定義が複数の依存パッケージにまたがっている複雑な構造に対応するため、深い解決能力が必要とされた。さらに、GitHubの自動化機能であるGitHub Actionsと連携させる際に、依存関係アップグレードのプルリクエストでは、package.jsonに既に新しいバージョンが書かれているため、新旧バージョンの比較が「同じバージョン同士」になってしまう問題があった。これはプルリクエストのタイトルから古いバージョンを読み取ることで解決された。

bumpscanは、単一のパッケージだけでなく、プロジェクト全体の依存関係を一度にチェックする機能も持っている。引数なしでnpx bumpscanと実行すれば、プロジェクト内のすべての依存関係について、アップグレードによる影響をまとめて確認できる。これは、モノレポ構成のプロジェクトでも有効だ。

さらに、--fixオプションを使うと、安全に自動で修正できる「リネーム」のような変更点については、直接コードを書き換えてくれる。例えば、chalkライブラリのLevelがColorSupportLevelにリネームされた場合、npx bumpscan chalk@5 --fixと実行すれば、該当するコードの行を自動で修正してくれる。ただし、人間の判断が必要な削除などの変更については、誤った修正を行うリスクを避けるため、自動修正は行わない。

bumpscanはGitHub Actionとしても提供されており、GitHubのワークフローに組み込むことで、すべての依存関係アップグレードのプルリクエストに対して、自動的にbumpscanの分析結果をコメントとして投稿させることが可能だ。これにより、開発チームはプルリクエストの段階で、アップグレードによる潜在的な問題を早期に把握できる。

もちろん、bumpscanにも限界がある。このツールはTypeScriptとJavaScriptのプロジェクトに特化しており、それ以外の言語には対応していない。また、型定義ファイルが提供されていないパッケージの場合、package.jsonのチェック以上の詳細な分析はできない。最も重要な制限として、関数の名前や引数のシグネチャは変わらないが、その関数の内部的な「振る舞い」や「返り値」が変わったような変更、つまり「論理的な変更」は検出できない。bumpscanは、あくまでコードの構造的な、機械的な破損を見つけるためのツールである。

この非常に有用なツールはMITライセンスで公開されており、GitHubでそのソースコードを確認できる。ぜひ、npx bumpscanとコマンドを実行して、あなたのプロジェクトで試してみてほしい。もし誤った情報が報告されたり、本来検出されるべき変更が見落とされたりした場合は、GitHubのIssueとして報告することを開発者は歓迎している。特に誤検出の報告は、ツールの精度向上に大きく貢献するそうだ。このツールは、システムエンジニアを目指すあなたにとって、将来のアップグレード作業を格段に効率化してくれる強力な味方となるだろう。