# 機能設計書 67-Javaクラス補完

## 概要

本ドキュメントは、Clojure LSPにおけるJavaクラス補完機能の設計を定義する。この機能は、Clojureコード内でJavaクラスやメンバーの補完候補を提供し、Java相互運用の開発効率を向上させる。

### 本機能の処理概要

**業務上の目的・背景**：ClojureはJVMベースの言語であり、Javaライブラリとの相互運用が重要な機能である。開発者がJavaクラスをインポートして使用する際、クラス名やメソッド名の補完が利用できると開発効率が大幅に向上する。この機能は、プロジェクトの依存関係にあるJavaクラスや、JDKの標準クラスに対する補完を提供する。

**機能の利用シーン**：
- `(:import ...)` 内でJavaクラス名を入力中に補完候補を表示
- Javaオブジェクトに対するメソッド呼び出し（`.methodName`）の補完
- 静的メソッド呼び出し（`ClassName/methodName`）の補完

**主要な処理内容**：
1. clj-kondoの解析結果からJavaクラス定義・使用情報を取得
2. JDKソースの解析結果からjava.*パッケージのクラス情報を取得
3. コンテキストに応じた補完候補をフィルタリング・ソートして返却

**関連システム・外部連携**：clj-kondoによるJavaクラス解析、JDKソース解析機能（No.69）、補完機能（No.1）と連携。

**権限による制御**：特に権限制御は存在しない。全ユーザーが同等にこの機能を利用できる。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 該当なし | 該当なし | 該当なし | 本機能はLSPプロトコルを通じてエディタから呼び出される |

## 機能種別

コード補完処理 / データ取得処理

## 入力仕様

### 入力パラメータ

本機能は補完機能（No.1）の一部として動作し、textDocument/completion リクエストを受ける。

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| uri | string | Yes | 対象ファイルのURI | 有効なファイルURI |
| position | object | Yes | カーソル位置 | {line, character} 形式 |

### 入力データソース

- LSPクライアントからの textDocument/completion リクエスト
- 内部DB（Javaクラス定義・使用情報）
- JDK解析キャッシュ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| CompletionItem[] | array | 補完候補リスト |
| label | string | 表示名（クラス名、メソッド名） |
| kind | enum | 補完種別（Class, Method, Field等） |
| detail | string | 詳細情報（パッケージ名、シグネチャ） |
| additionalTextEdits | array | 追加編集（import文の追加等） |

### 出力先

LSPクライアント（JSON-RPC レスポンス）

## 処理フロー

### 処理シーケンス

```
1. textDocument/completion リクエストを受信
   └─ completion.clj でコンテキストを解析
2. Javaクラス補完が必要なコンテキストか判定
   └─ import文内、Javaメソッド呼び出し等を検出
3. 解析データからJavaクラス/メンバー情報を取得
   └─ queries.clj の xf-analysis->java-class-definitions 等を使用
4. コンテキストに応じた補完候補を生成
   └─ インポート済みクラス、クラスパス上のクラス、JDKクラス
5. 補完候補をソート・返却
```

### フローチャート

```mermaid
flowchart TD
    A[completion リクエスト] --> B[コンテキスト解析]
    B --> C{Java補完コンテキスト?}
    C -->|No| D[通常の補完処理]
    C -->|Yes| E[Javaクラス情報取得]
    E --> F{import文内?}
    F -->|Yes| G[クラス名補完]
    F -->|No| H{メソッド呼び出し?}
    H -->|Yes| I[メソッド補完]
    H -->|No| J[静的メンバー補完]
    G --> K[候補生成・返却]
    I --> K
    J --> K
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | インポート優先 | 既にインポートされているクラスを優先表示 | クラス名補完時 |
| BR-02 | パッケージ表示 | 完全修飾名のパッケージ部分をdetailに表示 | クラス名補完時 |
| BR-03 | 自動インポート | 未インポートクラスは additionalTextEdits でインポートを追加 | クラス選択時 |

### 計算ロジック

**クラス名マッチング**:
- プレフィックスマッチによるフィルタリング
- 大文字・小文字を区別しない検索

## データベース操作仕様

### 操作別データベース影響一覧

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| クラス定義取得 | db[:analysis][:java-class-definitions] | SELECT | Javaクラス定義一覧を取得 |
| クラス使用取得 | db[:analysis][:java-class-usages] | SELECT | Javaクラス使用一覧を取得 |
| メンバー定義取得 | db[:analysis][:java-member-definitions] | SELECT | Javaメンバー定義一覧を取得 |

### テーブル別操作詳細

#### db[:analysis][:java-class-definitions]

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | :class, :uri | 全件またはプレフィックスマッチ | xf-analysis->java-class-definitions |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 空リスト | Javaクラスが見つからない | 空の補完リストを返却 |

### リトライ仕様

リトライは不要。

## トランザクション仕様

読み取り専用処理のため、トランザクション管理は不要。

## パフォーマンス要件

- 補完候補の表示は200ms以内を目標

## セキュリティ考慮事項

- 特になし

## 備考

- Java補完は completion.clj の一部として実装されている
- JDKソース解析（No.69）が有効な場合、java.*パッケージの補完精度が向上

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

Javaクラス解析データの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | queries.clj | `lib/src/clojure_lsp/queries.clj` | xf-analysis->java-class-definitions（98行目） |
| 1-2 | queries.clj | `lib/src/clojure_lsp/queries.clj` | xf-analysis->java-member-definitions（100行目） |

**読解のコツ**: Javaクラス定義は :java-class-definitions バケットに、メンバーは :java-member-definitions バケットに格納される。各要素は :class, :method-name, :uri などを持つ。

#### Step 2: 補完機能との統合を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | completion.clj | `lib/src/clojure_lsp/feature/completion.clj` | Javaクラス補完のコンテキスト判定 |

**読解のコツ**: completion.clj はカーソル位置のコンテキストを解析し、適切な補完候補生成器を呼び出す。

#### Step 3: Java相互運用機能を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | java_interop.clj | `lib/src/clojure_lsp/feature/java_interop.clj` | Java相互運用のユーティリティ関数群 |

**主要処理フロー**:
- Javaクラス情報の取得
- JDKソース解析との連携

### プログラム呼び出し階層図

```
handlers.clj::completion
    │
    └─ feature/completion.clj::completion
           │
           ├─ (コンテキスト解析)
           │
           └─ (Java補完コンテキストの場合)
                  │
                  ├─ queries.clj::xf-analysis->java-class-definitions
                  │
                  ├─ queries.clj::xf-analysis->java-class-usages
                  │
                  └─ queries.clj::xf-analysis->java-member-definitions
```

### データフロー図

```
[入力]                    [処理]                              [出力]

補完リクエスト  ───▶  completion.clj
                          │
                          ▼
                   コンテキスト解析
                          │
                          ▼
                   Javaクラス情報取得
                   (:java-class-definitions
                    :java-member-definitions)
                          │
                          ▼
                   プレフィックスフィルタリング
                          │
                          ▼
                   CompletionItem生成
                          │
                          ▼
                   補完候補[]  ───▶  LSPクライアント
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| completion.clj | `lib/src/clojure_lsp/feature/completion.clj` | ソース | 補完機能のメインロジック |
| java_interop.clj | `lib/src/clojure_lsp/feature/java_interop.clj` | ソース | Java相互運用ユーティリティ |
| queries.clj | `lib/src/clojure_lsp/queries.clj` | ソース | Javaクラスクエリ関数群 |
| handlers.clj | `lib/src/clojure_lsp/handlers.clj` | ソース | 補完ハンドラ |
