# 画面設計書 11-名前変更準備

## 概要

本ドキュメントは、Lua Language Serverの「名前変更準備（textDocument/prepareRename）」機能の画面設計書である。この機能は、シンボルの名前変更操作を実行する前に、変更可能かどうかを事前確認し、現在の名前を取得するLSP機能を提供する。

### 本画面の処理概要

この機能では、ユーザーがコード内のシンボル（変数、関数、フィールド等）の名前変更を試みる前に、そのシンボルが名前変更可能かどうかを検証し、可能な場合は現在の名前と変更対象範囲を返却する。

**業務上の目的・背景**：名前変更（リネーム）はリファクタリングにおいて最も頻繁に使用される機能の一つである。しかし、すべてのシンボルが名前変更可能とは限らない。たとえば、組み込み関数やライブラリ由来のシンボルは変更すべきではない。prepareRename機能により、ユーザーは実際の名前変更操作を実行する前に、その操作が可能かどうかを確認でき、不適切な操作を防止できる。また、現在の名前を取得することで、エディタ側でインライン編集UIを適切に表示できる。

**画面へのアクセス方法**：エディタ上でシンボルにカーソルを合わせ、名前変更コマンド（通常F2キーまたはコンテキストメニューから「名前の変更」）を実行した際に、この機能が最初に呼び出される。エディタはこのリクエストの結果に基づいて、インライン編集ダイアログを表示するか、エラーメッセージを表示するかを決定する。

**主要な操作・処理内容**：
1. カーソル位置のソースコードを解析し、対象シンボルを特定する
2. シンボルの種類（ローカル変数、グローバル変数、フィールド、メソッド等）を判定する
3. 名前変更可能なシンボルタイプかどうかを検証する
4. 可能な場合、シンボルの現在の名前と選択範囲を返却する

**画面遷移**：この機能が成功した場合、エディタは「名前変更（textDocument/rename）」機能を呼び出して実際の変更を実行する。失敗した場合、ユーザーに名前変更が不可能である旨のメッセージが表示される。

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 23 | リネーム準備 (textDocument/prepareRename) | 主機能 | 名前変更可能かを事前確認する主処理 |
| 22 | リネーム (textDocument/rename) | 遷移先機能 | prepareRename成功後に呼び出される名前変更実行処理 |

## 画面種別

LSP機能（事前確認）

## URL/ルーティング

LSPメソッド: `textDocument/prepareRename`

## 入出力項目

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

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| textDocument | TextDocumentIdentifier | Yes | 対象ドキュメントのURI |
| position | Position | Yes | カーソル位置（行・列） |

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

| 項目名 | 型 | 説明 |
|--------|-----|------|
| range | Range | 変更対象のテキスト範囲（開始位置・終了位置） |
| placeholder | string | 現在のシンボル名（インライン編集の初期値） |

## 表示項目

LSP機能のため、表示はエディタ（クライアント）側が担当する。サーバーからは以下の情報を返却する。

| 表示項目 | 説明 |
|---------|------|
| 選択範囲 | シンボルの開始位置から終了位置まで |
| プレースホルダー | 現在のシンボル名 |

## イベント仕様

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

1. クライアントからtextDocument/prepareRenameリクエストを受信
2. ドキュメントURIから対象ファイルのASTを取得
3. カーソル位置からソースコード要素を特定（findSource関数）
4. シンボルタイプが名前変更可能（accept table）かを判定
5. 可能な場合、prepareRename関数でシンボル情報を取得
6. 範囲（range）と現在の名前（placeholder）をレスポンスとして返却

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

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

この機能はデータベース操作を行わない。ファイルシステム上のソースコードを読み取るのみで、変更は行わない。

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| prepareRenameリクエスト | なし | SELECT（読み取り） | ソースコードの解析のみ |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|---------|
| - | 成功 | （レスポンスデータ返却） | 名前変更可能なシンボルが見つかった場合 |
| - | 失敗 | null | 名前変更不可能なシンボル、または対象が見つからない場合 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| ファイルが見つからない | nullを返却 |
| ASTの取得に失敗 | nullを返却 |
| カーソル位置にシンボルがない | nullを返却 |
| 対象が名前変更不可能なタイプ | nullを返却 |

## 備考

- この機能は名前変更の「事前確認」であり、実際の変更は行わない
- 名前変更可能なシンボルタイプは `accept` テーブルで定義されている
- サポートされるシンボルタイプ: label, goto, local, setlocal, getlocal, field, method, tablefield, setglobal, getglobal, string, boolean, number, integer, doc.class.name, doc.type.name, doc.alias.name, doc.param.name, doc.enum.name, doc.field.name, doc.extends.name

---

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

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

### 推奨読解順序

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

まず、LSPプロトコルで定義されるリクエスト・レスポンスの構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | define.lua | `script/proto/define.lua` | LSPで使用される各種定義（Position, Range等） |
| 1-2 | converter.lua | `script/proto/converter.lua` | 位置情報の変換処理（packRange, unpackPosition） |

**読解のコツ**: LSPプロトコルでは位置情報が0-based（行・列ともに0から開始）で表現されるが、内部処理では異なる表現を使用する場合がある。converter.luaがこの変換を担当している。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | provider.lua | `script/provider/provider.lua` | textDocument/prepareRenameの登録（600-619行目） |

**主要処理フロー**:
1. **600行目**: `m.register 'textDocument/prepareRename'`でハンドラー登録
2. **602-603行目**: `core.rename`モジュールをrequireし、ファイル状態を取得
3. **609行目**: カーソル位置をLSP形式から内部形式に変換
4. **610行目**: `core.prepareRename`関数を呼び出し
5. **614-617行目**: 結果をLSP形式に変換して返却

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

名前変更準備のコアロジックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | rename.lua | `script/core/rename.lua` | prepareRename関数（444-464行目） |
| 3-2 | find-source.lua | `script/core/find-source.lua` | カーソル位置からソース要素を検索 |

**主要処理フロー**:
- **364-387行目**: `accept`テーブル - 名前変更可能なシンボルタイプの定義
- **327-362行目**: `prepareRename`関数 - シンボルタイプに応じた名前取得ロジック
- **444-464行目**: `m.prepareRename`関数 - 公開API、findSourceでシンボル特定後、prepareRename呼び出し

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

```
textDocument/prepareRename (provider.lua:600-619)
    |
    +-- files.getRealUri (ファイルURI正規化)
    |
    +-- files.getState (AST取得)
    |
    +-- converter.unpackPosition (位置変換)
    |
    +-- core/rename.prepareRename (rename.lua:444-464)
           |
           +-- findSource (find-source.lua)
           |      |
           |      +-- guide.eachSourceContain (対象ソース検索)
           |
           +-- prepareRename (rename.lua:327-362)
                  |
                  +-- source.type判定（acceptテーブル照合）
                  |
                  +-- シンボル名・範囲取得
```

### データフロー図

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

PrepareRenameParams            provider.lua                         PrepareRenameResult
+------------------+           +------------------+                 +----------------+
| textDocument.uri |  ------>  | ファイル状態取得   |                 | range          |
| position         |           | AST解析          |                 |   start        |
+------------------+           | ソース検索        |  ------------> |   end          |
                               | 名前変更可否判定   |                 | placeholder    |
                               +------------------+                 +----------------+
                                      |
                                      v
                               rename.lua
                               +------------------+
                               | findSource       |
                               | prepareRename    |
                               | accept判定       |
                               +------------------+
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| provider.lua | `script/provider/provider.lua` | ソース | LSPメソッドハンドラー登録 |
| rename.lua | `script/core/rename.lua` | ソース | 名前変更コアロジック |
| find-source.lua | `script/core/find-source.lua` | ソース | カーソル位置からソース要素検索 |
| converter.lua | `script/proto/converter.lua` | ソース | 位置・範囲のフォーマット変換 |
| files.lua | `script/files.lua` | ソース | ファイル管理・AST取得 |
| guide.lua | `script/parser/guide.lua` | ソース | AST操作ユーティリティ |
