Ummon

██╗   ██╗███╗   ███╗███╗   ███╗ ██████╗ ███╗   ██╗
██║   ██║████╗ ████║████╗ ████║██╔═══██╗████╗  ██║
██║   ██║██╔████╔██║██╔████╔██║██║   ██║██╔██╗ ██║
██║   ██║██║╚██╔╝██║██║╚██╔╝██║██║   ██║██║╚██╗██║
╚██████╔╝██║ ╚═╝ ██║██║ ╚═╝ ██║╚██████╔╝██║ ╚████║
 ╚═════╝ ╚═╝     ╚═╝╚═╝     ╚═╝ ╚═════╝ ╚═╝  ╚═══╝

"WHAT ARE THE ACTIVITIES OF A SYSTEM?
 I HAVE NOT THE SLIGHTEST IDEA.
 THE PATH APPEARS"

⚠️ 警告：このプロジェクトは開発初期段階にあり、まだ安定していません。バージョン間で API や機能が大幅に変更される可能性があります。

Ummon は、コードベースからナレッジグラフを構築するコード分析ツールです。コードへの理解を深め、AI による支援を向上させ、高度なクエリを可能にします。コードエンティティ（関数、クラス、モジュール）とドメイン概念を結び付けることで、複雑なソフトウェアシステムについて推論し、特定のタスクに関係するコードを見つけやすくします。

Dan Simmons の『Hyperion Cantos』に登場する AI、Ummon にちなんで名付けられたこのプロジェクトは、人間と AI アシスタントの双方がソフトウェアシステムをより深く理解できるよう、コードベースに関する詳細な洞察を提供します。

主な機能

1. ナレッジグラフの構築

   • コードにインデックスを付け、セマンティック表現を作成します
   • コードエンティティ間の関係（呼び出し、インポート、依存関係）をマッピングします
   • 複数の言語（Rust、Python、JavaScript、Java）に対応しています
   • 差分更新と全体の再構築の両方に対応しています
   • ファイルの変更を追跡し、再処理を最小限に抑えます
   • 詳細はナレッジグラフのドキュメントをご覧ください

2. 高度なクエリシステム

   • 強力な構造化クエリ言語または自然言語を使って、コードベースにクエリを実行できます
   • 主なクエリの種類は 2 つあります：
     • Select クエリ：select [entity_type] where [conditions]
     • トラバーサルクエリ：[source_type] [relationship] [target_type] where [conditions]
   • 使いやすいインタラクションを実現する自然言語への変換
   • 属性条件と論理演算子による柔軟なフィルタリング
   • 複数の出力形式（テキスト、JSON、CSV、ツリー）
   • 例：「select functions where name like 'auth%'」、「すべての認証関数を表示」
   • 詳細はクエリシステムのドキュメントをご覧ください

3. 関連性エージェント

   • 提案された変更やクエリに関係するコードファイルを提案します
   • 自然言語の説明から技術的なキーワードを抽出するために、セマンティック分析を使用します
   • エンティティ間の関係を利用して、ナレッジグラフ内の関連エンティティを特定します
   • 近接性とグラフ中心性の両方の指標を使って、ファイルの関連性をスコア化します
   • 関連性の高いファイルを順位付けした一覧で、コンテキストを考慮した支援を実現します
   • 例：「認証バグを修正する」の場合、認証関連のファイルを特定します
   • 詳細は関連性エージェントのドキュメントをご覧ください

4. ドメインモデルの抽出

   • LLM を使ってビジネスエンティティと概念を特定します
   • ドメイン概念を実装の詳細にマッピングします
   • 技術面の理解とビジネス面の理解を結び付けます
   • 詳細はドメイン抽出のドキュメントをご覧ください

インストールとセットアップ

cargo install ummon

使い方

# Index a codebase (performs incremental update by default)
ummon index /path/to/codebase

# Perform a full rebuild of the knowledge graph
ummon index /path/to/codebase --full

# Index with domain model extraction enabled
ummon index /path/to/codebase --enable-domain-extraction

# Specify a custom domain directory for extraction
ummon index /path/to/codebase --enable-domain-extraction --domain-dir models/

# Query using natural language
ummon query "show all authentication functions"

# Query using structured query language
ummon query "select functions where name like 'auth%'" --no-llm

# Find relationships between entities (traversal query)
ummon query "functions calling functions where name like 'validate%'" --no-llm

# Query with different output formats
ummon query "select functions" --format json
ummon query "select functions" --format csv
ummon query "select functions" --format tree

# Filter query results by type
ummon query "find api" --type-filter function

# Filter by file path pattern
ummon query "show all entities" --path src/auth

# Limit the number of results
ummon query "select functions" --limit 10

# Skip LLM processing for structured queries
ummon query "select functions where file_path like 'src/auth/%'" --no-llm

# Generate AI-assisted recommendations
ummon assist "implement a user registration function"

# Get relevant file suggestions for a proposed change
ummon assist --suggest-files "fix authentication token validation"

設定

Ummon では、機密情報にのみ環境変数を使用します。

• OPENROUTER_API_KEY：LLM サービスの API キー（クエリとドメイン抽出に必要です）

それ以外の設定はすべて、コマンドラインフラグで行います。

アーキテクチャ

Ummon はモジュール式のアーキテクチャで構築されています。

• コード分析用の言語固有パーサー
• エンティティと関係を保存するグラフベースのストレージ
• 効率的な更新のためのメタデータ追跡機能を備えた SQLite データベース
• 差分インデックス作成のためのインテリジェントな更新メカニズム
• セマンティックな理解のための LLM 統合
• コンテキストを考慮した支援のための関連性エージェント
• ユーザー操作のためのコマンドラインインターフェース

言語サポート

Ummon は、複数のプログラミング言語の解析と分析に対応しています。

• Rust：クラス／構造体、トレイト、実装、関数、モジュール
• Python：クラス、関数、デコレーター、インポート
• JavaScript：クラス、関数、アロー関数、インポート
• Java：クラス、インターフェース、メソッド、コンストラクター、フィールド

Java パーサーは、以下の解析に対応しています。

• 修飾子を含むクラスおよびインターフェースの定義
• コンストラクターの宣言
• パラメーター型を含むメソッドの宣言
• 型を含むフィールドの宣言
• パッケージの宣言とインポート（ワイルドカードおよび静的インポートを含む）
• ドキュメントコメントの抽出
• メソッド呼び出しと関係性

ナレッジグラフの更新

Ummon では、ナレッジグラフを更新する方法として、次の 2 つの方法を利用できます。

増分更新（デフォルト）

--full フラグを指定せずに実行すると、Ummon は増分更新を行います。

• 最後にインデックスを作成した操作のタイムスタンプを記録します
• ファイルの変更時刻を使って、前回のインデックス作成以降に変更されたファイルを検出します
• 変更されたファイルに関連するエンティティと関係性のみを削除します
• 変更されたファイルのみを再インデックスし、グラフの残りの部分は保持します
• 小規模な変更がある大規模なコードベースで、大幅に高速化できます

全体の再構築

--full フラグを指定して実行すると、Ummon は完全な再構築を行います。

• データベースからすべてのエンティティと関係性を削除します
• コードベース全体を最初から再インデックスします
• 大幅な変更の後や、グラフの整合性が損なわれている可能性がある場合に便利です

ドキュメント

詳細なドキュメントについては、以下を参照してください。

• はじめに：インストールとクイックスタートガイド
• 機能ドキュメント：各機能の詳細なドキュメント
• CLI リファレンス：コマンドラインの完全なリファレンス
• 設定：設定オプションとベストプラクティス

開発

ビルドとテストのコマンド

# Build the project
cargo build

# Run the project
cargo run

# Run with specific command
cargo run -- index .              # Incremental index of current directory
cargo run -- index . --full       # Full rebuild of the knowledge graph
cargo run -- query "show funcs"   # Query the knowledge graph

# Run tests
cargo test
cargo test -- --nocapture  # Show test output
cargo test <test_name>     # Run specific test

# Format code
cargo fmt

テストリソース

• test/java/：パーサーテスト用の Java テストファイル
  • Test.java：基本的な解析用のシンプルな Java クラス
  • ComplexExample.java：高度な Java の機能（ジェネリクス、アノテーションなど）
• test/javascript/：テスト用の JavaScript テストファイル

ライセンス

Apache ライセンス