# 画面設計書 14-コードアクション

## 概要

本ドキュメントは、Lua Language Serverの「コードアクション（textDocument/codeAction）」機能の画面設計書である。この機能は、コードの問題に対するクイックフィックスやリファクタリング候補を提供する。

### 本画面の処理概要

この機能では、指定された範囲と診断情報に基づいて、適用可能なコードアクション（修正候補、リファクタリング操作）の一覧を返却する。ユーザーはこれらのアクションを選択して、コードの自動修正やリファクタリングを実行できる。

**業務上の目的・背景**：コーディング中に発生するエラーや警告に対して、手動で修正を行うのは時間がかかり、誤りも起きやすい。コードアクション機能により、診断結果に基づいた自動修正や、コードの改善提案を即座に適用でき、開発効率と品質が向上する。また、JSONからLuaへの変換など、定型的なリファクタリング作業も自動化できる。

**画面へのアクセス方法**：エディタ上でエラーや警告の下線が表示されている箇所にカーソルを合わせ、電球アイコンをクリックするか、クイックフィックスコマンド（Ctrl+.等）を実行することで、この機能が呼び出される。

**主要な操作・処理内容**：
1. 対象範囲と診断情報を受け取る
2. 診断コードに応じたクイックフィックスを生成する
3. 選択範囲に応じたリファクタリング候補を生成する
4. 適用可能なコードアクションの一覧を返却する

**画面遷移**：ユーザーがアクションを選択すると、対応するコマンド（lua.solve, lua.removeSpace, lua.setConfig等）が実行される。コマンド実行後、コードが自動的に修正される。

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 24 | コードアクション (textDocument/codeAction) | 主機能 | クイックフィックス・リファクタリング候補を表示する主処理 |
| 26 | 問題解決 (lua.solve) | 遷移先機能 | 診断の自動修正を実行 |
| 25 | スペース除去 (lua.removeSpace) | 遷移先機能 | 不要なスペースを除去 |
| 27 | JSONからLuaへ変換 (lua.jsonToLua) | 遷移先機能 | JSONデータをLuaテーブルに変換 |

## 画面種別

LSP機能（アクション一覧）

## URL/ルーティング

LSPメソッド: `textDocument/codeAction`

## 入出力項目

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

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| textDocument | TextDocumentIdentifier | Yes | 対象ドキュメントのURI |
| range | Range | Yes | 対象範囲 |
| context.diagnostics | Diagnostic[] | Yes | 対象範囲の診断情報 |

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

| 項目名 | 型 | 説明 |
|--------|-----|------|
| actions | CodeAction[] | コードアクション配列 |

### CodeAction構造

| 項目名 | 型 | 説明 |
|--------|-----|------|
| title | string | アクションの表示名 |
| kind | CodeActionKind | アクション種別（quickfix, refactor等） |
| edit | WorkspaceEdit | 適用する編集内容（オプション） |
| command | Command | 実行するコマンド（オプション） |

## 表示項目

| 表示項目 | 説明 |
|---------|------|
| アクションタイトル | 「診断を無効化」「グローバルとしてマーク」等 |
| アクション種別アイコン | quickfix/refactorに応じたアイコン |

## イベント仕様

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

1. クライアントからtextDocument/codeActionリクエストを受信
2. 範囲と診断情報を取得
3. checkQuickFix関数で診断に対するクイックフィックスを生成
4. checkSwapParams関数でパラメータ入れ替えアクションを生成
5. checkJsonToLua関数でJSON変換アクションを生成
6. checkMissingRequire関数で自動require挿入アクションを生成
7. 結果をLSP形式に変換してレスポンスを返却

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

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

この機能自体はデータベース操作を行わない。返却されるアクションを実行した際にファイルが更新される。

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| codeActionリクエスト | なし | SELECT（読み取り） | アクション候補の生成のみ |
| アクション実行 | ファイル | UPDATE | ソースコードの修正 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|---------|
| ACTION_DISABLE_DIAG | アクション | 「{code}を無効化」 | 診断を無効化する際 |
| ACTION_DISABLE_DIAG_LINE | アクション | 「{code}をこの行で無効化」 | 行単位で無効化 |
| ACTION_DISABLE_DIAG_FILE | アクション | 「{code}をこのファイルで無効化」 | ファイル単位で無効化 |
| ACTION_MARK_GLOBAL | アクション | 「{name}をグローバルとしてマーク」 | 未定義グローバル対応 |
| ACTION_RUNTIME_VERSION | アクション | 「Luaバージョンを{version}に変更」 | バージョン変更 |
| ACTION_ADD_SEMICOLON | アクション | 「セミコロンを追加」 | newline-call対応 |
| ACTION_ADD_BRACKETS | アクション | 「括弧を追加」 | ambiguity-1対応 |
| ACTION_REMOVE_SPACE | アクション | 「スペースを削除」 | trailing-space対応 |
| ACTION_MARK_ASYNC | アクション | 「@asyncとしてマーク」 | await-in-sync対応 |
| ACTION_ADD_DICT | アクション | 「{word}を辞書に追加」 | spell-check対応 |
| ACTION_SWAP_PARAMS | アクション | 「パラメータを入れ替え」 | リファクタリング |
| ACTION_JSON_TO_LUA | アクション | 「JSONをLuaに変換」 | JSON変換 |
| ACTION_AUTOREQUIRE | アクション | 「{target}をrequire」 | 自動require |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| ファイルが見つからない | nullを返却 |
| ASTの取得に失敗 | nullを返却 |
| 適用可能なアクションがない | nullを返却 |

## 備考

- CodeActionKindは以下を含む: '', 'quickfix', 'refactor.rewrite', 'refactor.extract'
- 診断コードに応じて異なるクイックフィックスが提供される
- undefined-global: グローバルマーク、Luaバージョン変更
- lowercase-global: グローバルマーク
- newline-call: セミコロン追加
- ambiguity-1: 括弧追加
- trailing-space: スペース削除
- await-in-sync: @async追加
- spell-check: 辞書追加、スペル修正候補

---

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

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

### 推奨読解順序

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

まず、CodeActionとCodeActionKindの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | provider.lua | `script/provider/provider.lua` (877-888行目) | codeActionKinds定義 |
| 1-2 | converter.lua | `script/proto/converter.lua` | command関数の構造 |

**読解のコツ**: CodeActionはedit（直接編集）またはcommand（コマンド実行）のいずれかを持つ。両方を持つ場合もある。

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

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

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

**主要処理フロー**:
1. **877行目**: `m.register 'textDocument/codeAction'`でハンドラー登録
2. **893-894行目**: ファイル状態取得
3. **903行目**: `core/code-action`モジュールを呼び出し
4. **910-923行目**: 結果のedit.changesをLSP形式に変換

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

コードアクション生成のコアロジックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | code-action.lua | `script/core/code-action.lua` | コードアクション生成の全体構造 |
| 3-2 | code-action.lua | `script/core/code-action.lua` (60-96行目) | disableDiagnostic関数 - 診断無効化アクション |
| 3-3 | code-action.lua | `script/core/code-action.lua` (136-156行目) | solveUndefinedGlobal関数 - 未定義グローバル対応 |
| 3-4 | code-action.lua | `script/core/code-action.lua` (427-451行目) | solveDiagnostic関数 - 診断種別ごとの処理分岐 |
| 3-5 | code-action.lua | `script/core/code-action.lua` (462-515行目) | checkSwapParams関数 - パラメータ入れ替え |
| 3-6 | code-action.lua | `script/core/code-action.lua` (630-680行目) | checkJsonToLua関数 - JSON変換 |
| 3-7 | code-action.lua | `script/core/code-action.lua` (690-732行目) | checkMissingRequire関数 - 自動require |

**主要処理フロー**:
- **60-96行目**: disableDiagnostic - 診断コードの無効化アクション生成
- **427-451行目**: solveDiagnostic - 診断コードに応じたsolver関数呼び出し
- **734-748行目**: メイン関数 - 全チェック関数の呼び出し

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

```
textDocument/codeAction (provider.lua:877-928)
    |
    +-- files.getRealUri (ファイルURI正規化)
    |
    +-- workspace.awaitReady (ワークスペース準備待機)
    |
    +-- files.getState (AST取得)
    |
    +-- converter.unpackRange (範囲変換)
    |
    +-- core/code-action (code-action.lua:734-748)
           |
           +-- checkQuickFix (453-460行目)
           |      |
           |      +-- solveDiagnostic (427-451行目)
           |             |
           |             +-- solveUndefinedGlobal
           |             +-- solveLowercaseGlobal
           |             +-- solveNewlineCall
           |             +-- solveAmbiguity1
           |             +-- solveTrailingSpace
           |             +-- solveAwaitInSync
           |             +-- solveSpell
           |             +-- disableDiagnostic
           |
           +-- checkSwapParams (462-556行目)
           |
           +-- checkJsonToLua (630-680行目)
           |
           +-- checkMissingRequire (690-732行目)
                  |
                  +-- autoreq.check (自動require候補)
```

### データフロー図

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

CodeActionParams               provider.lua                        CodeAction[]
+------------------+           +------------------+                 +------------------+
| textDocument.uri |  ------>  | ファイル状態取得   |                 | title            |
| range            |           | AST解析          |                 | kind             |
| context          |           +------------------+                 | edit             |
|   diagnostics[]  |                  |                             |   changes        |
+------------------+                  v                             | command          |
                               code-action.lua                      |   command        |
                               +------------------+                 |   arguments      |
                               | checkQuickFix    |                 +------------------+
                               |   solveDiagnostic|  ------------>
                               | checkSwapParams  |
                               | checkJsonToLua   |
                               | checkMissingRequire|
                               +------------------+
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| provider.lua | `script/provider/provider.lua` | ソース | LSPメソッドハンドラー登録 |
| code-action.lua | `script/core/code-action.lua` | ソース | コードアクション生成コアロジック |
| language.lua | `script/language.lua` | ソース | アクションタイトルの多言語対応 |
| auto-require.lua | `script/core/completion/auto-require.lua` | ソース | 自動require候補生成 |
| spell.lua | `script/provider/spell.lua` | ソース | スペル修正候補生成 |
| converter.lua | `script/proto/converter.lua` | ソース | Range/Edit変換処理 |
| files.lua | `script/files.lua` | ソース | ファイル管理・AST取得 |
| guide.lua | `script/parser/guide.lua` | ソース | AST操作ユーティリティ |
