Swark：コードからアーキテクチャ図を作成できるVSCode拡張

ソースコードから図を自動作成する方法というと、古くはDoxygenとGraphviz、PlantUMLなんかがありましたが、大規模なソースコードを人間が直接全部読むのはしんどいから、抽象的な図に可視化して全体像をできるだけ直感的に把握する術が欲しいもの。

SwarkはLLM(GitHub Copilot経由)によってソースコードからアーキテクチャ図を自動作成してくれるオープンソースのVSCode拡張。Visual Studio Marketplaceで配布されているので簡単にVSCodeにインストールできる。

Swark

Swarkは、大規模言語モデル(LLM)を用いてコードからアーキテクチャ図を自動作成できるVS Code拡張機能です。
SwarkはGitHub Copilotに直接統合されており、認証やAPIキーは不要です。

Swarkを選ぶ理由

• 🌟 無料かつオープンソース：Swarkは現在無料で利用でき、必要なのはGitHub Copilotのみです。Swarkのコードを読んで動作を理解し、改善に貢献することもできます。
• 🌍 ユニバーサル言語サポート：従来のコード可視化ソリューションは決定論的で、新しい言語やフレームワークへ対応するには段階的な追加サポートが必要でした。Swarkは、全ての「ロジック」がLLM内にカプセル化されているため、全ての言語をネイティブにサポートします。
• 🔑 シームレスな統合：SwarkはGitHub Copilotと直接統合されており、追加の設定や認証、APIキーは不要です。
• 🛡️ プライバシー第一：ソースコードはGitHub Copilotとのみ共有され、他の外部APIやプロバイダーには送信されません。
• 🧜‍♀️ Mermaid.js：Swarkは、人気のdiagram-as-codeフレームワークであるMermaid.jsでダイアグラムを生成します。必要に応じてダイアグラムを編集・改良することもできます。

ユースケース

• 🔎 新しいコードベースの学習：アーキテクチャ図を瞬時に生成し、馴染みのないリポジトリを高レベルで理解できます。オンボーディングや新規プロジェクトの取り組みに最適です。
• 🤖 AI生成コードのレビュー：AI生成プロジェクトが一般的になるにつれ、SwarkはAI生成コードの構造を迅速に視覚化し、基準を満たしているかを確認できます。
• 📕 ドキュメントの改善：数分で作成できる最新のアーキテクチャ図を使用して、ドキュメントを最新かつ詳細な状態に保ちます。
• 🕰️ レガシーコードの理解：レガシーコードベースの構造を迅速に視覚化して理解することで、メンテナンスとリファクタリングが容易になります。
• 🧩 設計上の欠陥の特定：リポジトリの依存関係グラフを視覚化し、不要な依存関係や最適化が必要な領域を特定します。
• ✅ テストカバレッジのインサイト：Swarkの入力にテストファイルを含めることで、テストカバレッジを一目で確認し、ギャップに対処できます。

依存関係

• GitHub Copilot：SwarkはGitHub Copilotを介してLLMクエリを呼び出します。Visual Studio MarketplaceからGitHub Copilot拡張機能をインストールしてください。GitHub Copilotは現在無料プランも提供しています。
• [オプション] Mermaid Markdown Preview：VS Codeで図をプレビューするには、Visual Studio MarketplaceからMarkdown Preview Mermaid Support拡張機能をインストールしてください。または、提供されるリンクからMermaid Live Editorで開くこともできます。

Vibe Codingが流行り始めてるけど、AIが秒速で大量のコードを書いてきても、それを受け取るのは人間なので、大量のコードを直接全部読まずに良し悪しをざっと判断する術の重要度は増しますね。

使い方

1. VS Codeでコマンドパレットを開き、Swark: Create Architecture Diagramを実行します。
   あるいは、以下のSwarkデフォルトキーバインドを使用することもできます。
   • Mac：cmd + shift + r
   • Windows：ctrl + shift + r
2. Swarkのファイル検索で使用するフォルダを選択します。
3. 数秒以内に、アーキテクチャ図を表示するタブが開きます。

出力

Swarkは、ワークスペースのルートフォルダ下のswark-outputフォルダに出力を保存します。
Swarkは実行ごとに以下2つの出力ファイルを作成します：

• ダイアグラムファイル：ダイアグラムのMermaidコードが含まれます。このファイルがSwark実行後にタブに表示されます。
  ファイル名：<date>__<time>__diagram.md
• ログファイル：実行、構成、およびダイアグラム作成に使用されたファイルに関する情報が含まれます。デバッグや問題報告に使用できます。
  ファイル名：<date>__<time>__log.md

出力されるファイルの例：

workspace-root
└── swark-output
    ├── 2025-01-09__20-18-38__diagram.md
    └── 2025-01-09__20-18-38__log.md

仕組み

1. ファイルの検索(Retrieval)：Swarkは指定されたフォルダ内のコードファイルを取得します。取得するファイルの数は、LLMトークンの最大制限数に合わせて自動的に調整されます。
2. プロンプトの構築：取得したファイルに基づいて、Swarkはアーキテクチャ図を生成するためのプロンプトを構築します。プロンプトにはコードファイルと図の構築手順が含まれます。
3. LLMリクエスト：SwarkはVS Code Language Model APIを介してGitHub CopilotにLLMリクエストを呼び出します。
4. ダイアグラムのプレビュー：レスポンスが成功すると、図が表示されます。これは、Mermaid構文で図を記述したマークダウンファイルの作成・プレビューによって実現されます。

コードへのアクセスとファイル共有

ソースコードはGitHub Copilotとのみ共有され、他の外部APIやプロバイダーとは共有されないことに注意してください。

拡張機能の設定

この拡張機能は以下の設定を提供します。

設定	説明
swark.maxFiles	読み取るファイルの最大数。 読み取るファイルの数はLLMの最大トークン制限によっても影響を受けます。
swark.fileExtensions	検索に含めるファイルの拡張子リスト。
swark.excludePatterns	ファイル検索から除外するglobパターンのリスト。 デフォルトでは 隠しファイル**/.* ノードモジュール**/node_modules/**が含まれています。
swark.languageModel	ダイアグラム生成に使用する言語モデル。
swark.fixMermaidCycles	生成されたMermaidダイアグラム内のサイクルを自動的に修正し、レンダリングの失敗を防ぎます。

試しにDUSt3Rのミニマムコードのリポジトリのアーキテクチャ図を作成してみた↓

DUSt3R：3Dコンピュータービジョンの基盤モデル

機械学習分野では、世間的にも話題のLLM(Large Language Model)をはじめ、多様な大量のデータでニューラルネットワークを事前学習(Pre-training)した基盤モデル(Foundation Model)が様々な下流タス...

blog.negativemind.com

2025.06.25