# 画面設計書 15-コードレンズ

## 概要

本ドキュメントは、Lua Language Serverの「コードレンズ（textDocument/codeLens）」機能の画面設計書である。この機能は、コード上に参照数などの追加情報をインラインで表示する機能を提供する。

### 本画面の処理概要

この機能では、ドキュメント内の関数定義に対して、その関数が参照されている回数などの情報をコード上に直接表示する。エディタはこの情報を関数定義の上部にクリック可能なテキストとして表示する。

**業務上の目的・背景**：コードを読む際に、ある関数がどの程度使用されているかを知ることは、リファクタリングの判断材料として重要である。コードレンズ機能により、関数の参照回数がコード上に直接表示されるため、コードの重要度や影響範囲を即座に把握できる。これにより、デッドコードの発見や、リファクタリング時の影響分析が容易になる。

**画面へのアクセス方法**：ファイルを開くと自動的にコードレンズが表示される。設定でLua.codeLens.enableがtrueの場合に有効となる。表示されたコードレンズをクリックすると、参照一覧が表示される。

**主要な操作・処理内容**：
1. ドキュメントのASTを取得し、関数定義を走査する
2. 各関数に対してコードレンズ情報（位置、ID）を生成する
3. クライアントからresolveリクエストを受け取り、実際の参照数を計算する
4. 参照数とクリック時のコマンドを返却する

**画面遷移**：コードレンズをクリックすると、参照一覧が表示される（lua.showReferencesコマンド）。参照一覧から特定の参照箇所を選択すると、その位置にジャンプする。

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 28 | コードレンズ (textDocument/codeLens) | 主機能 | 参照数などのインライン情報を表示する主処理 |
| 16 | 参照検索 (textDocument/references) | 補助機能 | 参照数のカウント処理 |

## 画面種別

LSP機能（インライン表示）

## URL/ルーティング

LSPメソッド: `textDocument/codeLens`

## 入出力項目

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

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| textDocument | TextDocumentIdentifier | Yes | 対象ドキュメントのURI |

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

| 項目名 | 型 | 説明 |
|--------|-----|------|
| codeLens | CodeLens[] | コードレンズ配列 |

### CodeLens構造

| 項目名 | 型 | 説明 |
|--------|-----|------|
| range | Range | 表示位置（関数定義の行） |
| data | object | resolve時に使用するデータ（uri, id） |

## 表示項目

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

## イベント仕様

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

1. クライアントからtextDocument/codeLensリクエストを受信
2. Lua.codeLens.enable設定を確認
3. ドキュメントのASTを取得
4. collectReferences関数で関数定義を走査し、コードレンズ情報を生成
5. 各コードレンズにposition, data.uri, data.idを設定
6. コードレンズ配列をレスポンスとして返却

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

1. クライアントからcodeLens/resolveリクエストを受信
2. data.uri, data.idからコードレンズを特定
3. resolveReference関数で参照数を計算
4. commandを設定してレスポンスを返却

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

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

この機能はデータベース操作を行わない。ソースコードを解析するのみで、変更は行わない。

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

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|---------|
| COMMAND_REFERENCE_COUNT | 表示 | 「{count} 個の参照」 | 参照数表示時 |
| - | 成功 | （コードレンズ配列返却） | コードレンズが見つかった場合 |
| - | 成功 | null | コードレンズが見つからない場合 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| ファイルが見つからない | nullを返却 |
| ASTの取得に失敗 | nullを返却 |
| Lua.codeLens.enableがfalse | 処理をスキップ |
| 関数定義がない | nullを返却 |

## 備考

- コードレンズはresolveProviderをtrueとして登録されており、実際の参照数計算は遅延評価される
- 関数定義（function型）のうち、代入式の右辺またはreturn文に含まれるもののみが対象
- client.getOption('codeLensViewReferences')がtrueの場合、lua.showReferencesコマンドで参照一覧を表示できる
- 設定Lua.codeLens.enableで機能の有効/無効を切り替え可能

---

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

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

### 推奨読解順序

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

まず、CodeLensとCommandの構造を理解する。

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

**読解のコツ**: コードレンズは2段階で処理される。最初のリクエストでは位置とIDのみを返し、resolveリクエストで実際のコマンドを計算する（遅延評価パターン）。

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

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

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

**主要処理フロー**:
1. **930行目**: `m.register 'textDocument/codeLens'`でハンドラー登録
2. **940-941行目**: Lua.codeLens.enable設定確認
3. **948行目**: `core.codeLens`関数を呼び出し
4. **953-962行目**: 結果をLSP形式に変換
5. **971行目**: resolveでは`core.resolve`関数を呼び出し

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

コードレンズ生成と参照数計算のコアロジックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | code-lens.lua | `script/core/code-lens.lua` | コードレンズ生成の全体構造 |
| 3-2 | code-lens.lua | `script/core/code-lens.lua` (28-40行目) | mt:init関数 - 初期化 |
| 3-3 | code-lens.lua | `script/core/code-lens.lua` (67-84行目) | mt:collectReferences関数 - 関数定義走査 |
| 3-4 | code-lens.lua | `script/core/code-lens.lua` (89-121行目) | mt:resolveReference関数 - 参照数計算 |
| 3-5 | code-lens.lua | `script/core/code-lens.lua` (126-145行目) | getCodeLens関数 - メイン処理 |

**主要処理フロー**:
- **67-84行目**: collectReferences - guide.eachSourceTypeで関数を走査し、代入式/return文の関数を収集
- **89-121行目**: resolveReference - getRef関数で参照を取得し、count計算とコマンド生成

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

```
textDocument/codeLens (provider.lua:930-965)
    |
    +-- config.get (Lua.codeLens.enable確認)
    |
    +-- workspace.awaitReady (ワークスペース準備待機)
    |
    +-- files.getState (AST取得)
    |
    +-- core/code-lens.codeLens (code-lens.lua:126-145)
           |
           +-- mt:init (28-40行目)
           |
           +-- mt:collectReferences (67-84行目)
                  |
                  +-- guide.eachSourceType('function', ...)
                  |
                  +-- guide.isAssign / parent.type == 'return'
                  |
                  +-- mt:addResult (44-51行目)

codeLens/resolve (provider.lua:967-975)
    |
    +-- core/code-lens.resolve (code-lens.lua:150-161)
           |
           +-- mt:resolve (53-64行目)
                  |
                  +-- mt:resolveReference (89-121行目)
                         |
                         +-- getRef (参照検索)
                         |
                         +-- conv.location (位置変換)
                         |
                         +-- conv.command (コマンド生成)
```

### データフロー図

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

CodeLensParams                 provider.lua                        CodeLens[]
+------------------+           +------------------+                 +------------------+
| textDocument.uri |  ------>  | config確認        |                 | range            |
+------------------+           | AST取得          |                 | data             |
                               | collectReferences|  ------------> |   uri            |
                               +------------------+                 |   id             |
                                                                   +------------------+

CodeLensResolveParams          provider.lua                        CodeLens
+------------------+           +------------------+                 +------------------+
| data.uri         |  ------>  | resolve          |                 | range            |
| data.id          |           | resolveReference |  ------------> | command          |
+------------------+           | getRef           |                 |   title          |
                               +------------------+                 |   command        |
                                                                   |   arguments      |
                                                                   +------------------+
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| 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` | ソース | Range/Command変換処理 |
| files.lua | `script/files.lua` | ソース | ファイル管理・AST取得 |
| guide.lua | `script/parser/guide.lua` | ソース | AST操作ユーティリティ |
| config.lua | `script/config.lua` | ソース | 設定管理 |
