# 画面設計書 16-コードレンズ詳細

## 概要

本ドキュメントは、Lua Language Serverの「コードレンズ詳細（codeLens/resolve）」機能の画面設計書である。この機能は、コードレンズの詳細情報（参照数、実行コマンド）を遅延取得する機能を提供する。

### 本画面の処理概要

この機能では、textDocument/codeLensで返却されたコードレンズに対して、実際の参照数計算やコマンド情報を遅延評価で取得する。これにより、初回のコードレンズ取得を高速化し、ユーザーがコードレンズを表示する際にのみ詳細計算を行う。

**業務上の目的・背景**：大規模なファイルでは多数の関数定義が存在し、すべての参照数を即座に計算するとパフォーマンスに影響する。コードレンズの遅延解決機能により、表示に必要な情報のみを必要なタイミングで計算することで、エディタの応答性を維持しながら詳細情報を提供できる。

**画面へのアクセス方法**：textDocument/codeLensでコードレンズ情報を取得した後、エディタが各コードレンズの表示時にこの機能を呼び出す。ユーザーが直接操作することはない。

**主要な操作・処理内容**：
1. コードレンズのdata（uri, id）を受け取る
2. 対応するコードレンズ情報を特定する
3. 参照検索を実行し、参照数を計算する
4. 表示テキストとクリック時のコマンドを返却する

**画面遷移**：解決されたコードレンズをクリックすると、設定に応じて参照一覧が表示される（lua.showReferencesコマンド）。

**権限による表示制御**：特になし。LSPプロトコルレベルでの認証・権限管理は行わない。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 29 | コードレンズ解決 (codeLens/resolve) | 主機能 | コードレンズの詳細情報を取得する主処理 |

## 画面種別

LSP機能（詳細取得）

## URL/ルーティング

LSPメソッド: `codeLens/resolve`

## 入出力項目

### 入力項目（リクエストパラメータ）

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| range | Range | Yes | コードレンズの表示位置 |
| data.uri | string | Yes | 対象ドキュメントのURI |
| data.id | number | Yes | コードレンズの識別ID |

### 出力項目（レスポンス）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| range | Range | コードレンズの表示位置 |
| command | Command | 実行コマンド情報 |

### Command構造

| 項目名 | 型 | 説明 |
|--------|-----|------|
| title | string | 表示テキスト（「N 個の参照」） |
| command | string | コマンド名（lua.showReferences） |
| arguments | array | コマンド引数（uri, position, locations） |

## 表示項目

| 表示項目 | 説明 |
|---------|------|
| 参照数テキスト | 「N 個の参照」形式のテキスト |
| クリック可能リンク | 参照一覧を表示するコマンドへのリンク |

## イベント仕様

### 1-codeLens/resolveリクエスト処理

1. クライアントからcodeLens/resolveリクエストを受信
2. data.uriとdata.idからコードレンズを特定
3. ファイル状態からキャッシュされたcodeLensオブジェクトを取得
4. mt:resolve関数で参照数を計算
5. commandを設定してレスポンスを返却
6. commandが取得できない場合は「...」を表示

## データベース更新仕様

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

この機能はデータベース操作を行わない。参照検索を実行するのみで、変更は行わない。

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| codeLens/resolveリクエスト | なし | SELECT（読み取り） | 参照数の計算のみ |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|---------|
| COMMAND_REFERENCE_COUNT | 表示 | 「{count} 個の参照」 | 参照数表示時 |
| - | フォールバック | 「...」 | コマンド取得失敗時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| ファイル状態が見つからない | 「...」コマンドを返却 |
| codeLensキャッシュが見つからない | 「...」コマンドを返却 |
| 解決に失敗 | 「...」コマンドを返却 |

## 備考

- codeLens/resolveはtextDocument/codeLensの後続処理として呼び出される
- 解決結果はファイル状態（state._codeLens）にキャッシュされる
- client.getOption('codeLensViewReferences')がtrueの場合、lua.showReferencesコマンドで参照一覧を表示可能
- falseの場合、クリック不可能な参照数テキストのみを表示

---

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

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

### 推奨読解順序

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

まず、resolving情報とCommand構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | code-lens.lua | `script/core/code-lens.lua` (9-19行目) | codeLens.resolvingクラス定義 |
| 1-2 | converter.lua | `script/proto/converter.lua` | command関数の構造 |

**読解のコツ**: resolving情報にはmode（現在は'reference'のみ）とsource（対象ソース要素）が含まれる。

#### Step 2: エントリーポイントを理解する

処理の起点となるプロバイダー登録を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | provider.lua | `script/provider/provider.lua` (967-975行目) | codeLens/resolveの登録 |

**主要処理フロー**:
1. **967行目**: `m.register 'codeLens/resolve'`でハンドラー登録
2. **970行目**: `core/code-lens`モジュールを読み込み
3. **971行目**: `core.resolve`関数を呼び出し
4. **972行目**: 結果がない場合は「...」コマンドを設定

#### Step 3: コア処理を理解する

コードレンズ解決のコアロジックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | code-lens.lua | `script/core/code-lens.lua` (150-161行目) | resolve関数 |
| 3-2 | code-lens.lua | `script/core/code-lens.lua` (53-64行目) | mt:resolve関数 |
| 3-3 | code-lens.lua | `script/core/code-lens.lua` (89-121行目) | mt:resolveReference関数 |

**主要処理フロー**:
- **150-161行目**: resolve関数 - ファイル状態からcodeLensオブジェクトを取得し、mt:resolveを呼び出し
- **53-64行目**: mt:resolve - resolving情報からモードを判定し、対応するresolver関数を呼び出し
- **89-121行目**: mt:resolveReference - getRefで参照を取得し、コマンドを生成

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

```
codeLens/resolve (provider.lua:967-975)
    |
    +-- core/code-lens.resolve (code-lens.lua:150-161)
           |
           +-- files.getState (ファイル状態取得)
           |
           +-- state._codeLens (キャッシュ取得)
           |
           +-- mt:resolve (53-64行目)
                  |
                  +-- resolving[id] (resolving情報取得)
                  |
                  +-- mt:resolveReference (89-121行目)
                         |
                         +-- getRef (参照検索)
                         |
                         +-- client.getOption('codeLensViewReferences')
                         |
                         +-- conv.location (位置変換)
                         |
                         +-- conv.command (コマンド生成)
```

### データフロー図

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

CodeLens (未解決)              provider.lua                        CodeLens (解決済)
+------------------+           +------------------+                 +------------------+
| range            |  ------>  | files.getState   |                 | range            |
| data.uri         |           | _codeLens取得    |                 | command          |
| data.id          |           +------------------+                 |   title          |
+------------------+                  |                             |   command        |
                                      v                             |   arguments      |
                               code-lens.lua                        +------------------+
                               +------------------+
                               | resolve          |
                               | resolving[id]    |  ------------>
                               | resolveReference |
                               | getRef           |
                               +------------------+
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| provider.lua | `script/provider/provider.lua` | ソース | LSPメソッドハンドラー登録 |
| code-lens.lua | `script/core/code-lens.lua` | ソース | コードレンズ解決コアロジック |
| reference.lua | `script/core/reference.lua` | ソース | 参照検索処理 |
| language.lua | `script/language.lua` | ソース | メッセージ多言語対応 |
| converter.lua | `script/proto/converter.lua` | ソース | Command変換処理 |
| files.lua | `script/files.lua` | ソース | ファイル管理・状態取得 |
| client.lua | `script/client.lua` | ソース | クライアントオプション取得 |
