【ITニュース解説】Building README star charts on GitHub's new star history endpoint

GitHubのような開発プラットフォームでは、多くのプロジェクトが公開されており、その人気度を示す一つの指標として「スター」がある。以前は、どのユーザーがプロジェクトにスターを付けたか、その一覧情報が誰でも確認できた。しかし、GitHubはセキュリティやプライバシーの観点から、このスターを付けたユーザー（スターゲイザー）の一覧を、プロジェクトの管理者や共同作業者のみが閲覧できるように変更した。これにより、これまで公開されていたスターゲイザーの一覧情報を利用して、プロジェクトの人気度の推移、つまりスターの履歴を可視化していた既存のツールが、データソースを失い機能しなくなってしまった。

この問題に対応するため、GitHubは今年9月に新しい機能、すなわち「スター履歴エンドポイント」を導入した。これは、まさにプロジェクトのスター履歴データを取得するために特別に設計されたものだ。この新しいエンドポイントを利用して、GitHubのREADME（プロジェクトの概要説明ファイル）内にスター数の変化を示すグラフを表示するツールが開発された。

新しいスター履歴エンドポイントは、GET /repos/{owner}/{repo}/stargazers/history という形式でアクセスできる。これは、Webサービスに対して特定の情報を要求するための「住所」のようなものだ。ここで{owner}にはリポジリトリの持ち主の名前、{repo}にはリポジトリ名が入る。例えば、Facebookが所有するReactというリポジトリであれば、facebook/reactといった形になる。このエンドポイントにアクセスすると、リポジトリのスター履歴データが、週ごとのまとまりで返ってくる。データは最新の週から順に並べられており、各週の合計スター数と、その週の各曜日（日曜日から始まる）に何個のスターが追加されたかの内訳が含まれる。非常に重要な点として、このエンドポイントは、公開されているあらゆるリポジトリに対して、認証なしで利用できる。つまり、GitHubのアカウントでログインする必要がなく、誰でも情報を取得できるため、様々なツールへの活用が期待される。また、リポジトリが途中で名前を変更した場合でも、その変更に追従して、古い名前のリポジトリのスター履歴も正しく取得できるという賢い仕組みを持っている。例えば、facebook/reactがreact/reactに名前を変えたとしても、どちらの名前でアクセスしても最終的には同じリポジトリの全履歴が返される。このエンドポイントから得られる週ごとの合計スター数は、複数の有名なリポジトリで実際のスター数と正確に一致することが確認されており、データの信頼性は高い。

データ取得のプロセスでは、リポジトリの作成日時から現在までの期間を計算し、必要なデータページ数を割り出す。このエンドポイントは一度に最大30週分のデータを返し、最大100ページまで要求できる。そのため、もしリポジトリが非常に古く、多くの週分の履歴が必要な場合でも、複数のページを順番にリクエストすることで対応可能だ。効率的にデータを取得するためには、必要なすべてのページを同時にリクエストする「並行処理」という手法が用いられる。これは、まるで複数の異なる情報を同時に読み込むようなもので、すべての情報が揃うのを待ってから次に進むため、全体の処理時間を大幅に短縮できる。取得されたデータは、最新の週から古い週へと並んでいるため、時系列順に並べ替えてから、各週のスター数を前の週までの合計に加算していくことで、累積スター数の推移グラフを作成する。最終的に、グラフの表示に適した約120点のデータポイントに間引かれ、また同じリポジトリへの繰り返しのリクエストを避けるため、取得した結果は1時間キャッシュされる仕組みになっている。

実は、この新しいエンドポイントが登場する前にも、スター履歴を取得するための別の試みがあった。それは「GH Archive」という、GitHub上の様々なイベントを記録している公開データを利用する方法だ。しかし、GH Archiveはリポジトリの「名前」でイベントを記録しているため、もしリポジトリが途中で名前を変えると、古い名前の時代の履歴と新しい名前の時代の履歴が別々に扱われてしまい、全体像を正確に把握できなかった。例えば、vuejs/coreというリポジトリは、以前vuejs/vue-nextという名前だったが、GH Archiveでは名前変更前の履歴が失われ、全体のスター数の半分程度しか表示されないという問題があったのだ。そのため、リネームされたリポジトリの古い名前を探し、それが本当に同じリポジトリであることをIDで確認する複雑な仕組みを独自に構築する必要があった。しかし、公式のスター履歴エンドポイントが提供されたことで、そのような複雑な処理は不要になり、より簡単に正確な履歴データが得られるようになった。

このスター履歴グラフをGitHubのREADMEに表示させるには、いくつか技術的な工夫が必要だ。GitHubのREADMEは、基本的に静的なテキストや画像しか表示できず、JavaScriptのようなプログラムを直接実行できない制約がある。そこで、グラフを「SVG（Scalable Vector Graphics）」という形式で作成する。SVGは、Webで使われるベクター画像フォーマットで、拡大・縮小しても画像が粗くならず、XMLという形式で記述されるため、Webブラウザや画像ビューアで表示できる。このグラフは、SvelteというWebアプリケーションを構築するためのフレームワークを使ってコンポーネントとして作成され、サーバー側でHTMLではなくSVGの画像としてレンダリングされる。具体的には、ユーザーが特定のURL（例：/owner/repo.svg）にアクセスすると、サーバーがSvelteコンポーネントを基にSVGコードを生成し、それを画像として返すという仕組みだ。これにより、READMEに![](https://starhistory.link/owner/repo.svg)のように画像として埋め込むだけで、動的なグラフを表示できる。グラフのアニメーションも、SVG内に直接CSSのキーフレームアニメーションを記述することで実現されている。例えば、グラフの線が描画されていくようなアニメーションや、グラフの領域が徐々にフェードインするような表現が可能だ。pathLengthという属性を使うことで、複雑なパスの長さを正確に把握し、アニメーションの速度や表示を制御できる。グラフのデザインは、標準的なものから、ブロック文字を使ったASCIIアート風、小さなロケットがカーブを辿るようなユニークなものまで、8種類のバリエーションが用意されている。

また、このグラフをSNSで共有する際のプレビュー画像（Open Graphイメージ）として利用するためには、PNG形式の画像が必要になる。しかし、SVGをPNGに変換する際に使用されるresvgというライブラリは、CSS変数（Webサイトのスタイルを管理するための柔軟な仕組み）やSVG内のCSSアニメーションを直接サポートしていないという制約がある。そのため、SNS共有用の画像は、アニメーションを含まず、CSS変数ではなく直接的な色指定を用いたシンプルなSVGとして別途作成される。そして、このシンプルなSVGを@resvg/resvg-jsというツールでPNG形式に変換する。この際、フォントも一緒にパッケージ化することで、表示環境に依存せず意図通りの画像が生成されるようになっている。

このように、新しいGitHubのスター履歴エンドポイントは、リポジトリの人気度を追跡し、それを魅力的なグラフとして可視化するための強力な基盤を提供する。このツールはstarhistory.linkで実際に試すことができ、そのソースコードもGitHubで公開されている。これにより、システムエンジニアを目指す初心者がAPIの利用方法、Web技術の連携、そしてユーザーインターフェースの実装における工夫を学ぶ良い例となっている。