# 画面設計書 25-インレイヒント

## 概要

本ドキュメントは、Lua Language Serverにおける「インレイヒント」機能の画面設計書です。LSPプロトコルの `textDocument/inlayHint` リクエストに対応し、コード内に型・パラメータ名などのヒントをインライン表示します。

### 本画面の処理概要

インレイヒント機能は、コードの可読性を向上させるために、エディタ上にインライン情報（型情報、パラメータ名、配列インデックス、awaitマーカー、セミコロン等）を表示する機能です。

**業務上の目的・背景**：Luaは動的型付け言語であるため、変数の型やパラメータの意味がコードから直接読み取りにくい場合があります。インレイヒント機能により、型推論結果やパラメータ名をコード上に直接表示することで、コードの理解を助けます。特に大規模なコードベースや、他の開発者が書いたコードを読む際に有効です。また、await呼び出しの可視化により、非同期処理の流れを把握しやすくなります。

**画面へのアクセス方法**：エディタ（VS Code等）で `Lua.hint.enable` 設定が有効な場合、Luaファイルを開くと自動的にインレイヒントが表示されます。表示される範囲は、エディタの可視領域に応じて動的に更新されます。

**主要な操作・処理内容**：
1. エディタが可視範囲の `textDocument/inlayHint` リクエストを送信
2. `Lua.hint.enable` 設定を確認
3. 以下の種類のヒントを生成：
   - 型ヒント（変数の型情報）
   - パラメータ名ヒント（関数呼び出し時の引数名）
   - awaitヒント（非同期呼び出しのマーカー）
   - 配列インデックスヒント（テーブルのインデックス表示）
   - セミコロンヒント（文末のセミコロン表示）
4. ヒント情報をInlayHint配列としてエディタに返却

**画面遷移**：独立した機能として動作し、特定の画面遷移はありません。ヒントはコード上にオーバーレイ表示されます。

**権限による表示制御**：`Lua.hint.enable` 設定がfalseの場合、インレイヒントは表示されません。また、各種ヒントタイプごとに個別の設定で表示制御が可能です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 45 | インレイヒント (textDocument/inlayHint) | 主機能 | コード内に型・パラメータ名などのヒントを表示する主処理 |
| 46 | インレイヒント解決 (inlayHint/resolve) | 補助機能 | インレイヒントの詳細情報を取得 |
| 52 | 型推論 (Type Inference) | 補助機能 | ヒント表示のための型情報を推論 |

## 画面種別

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

## URL/ルーティング

LSPメソッド: `textDocument/inlayHint`

## 入出力項目

### 入力パラメータ

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| textDocument | TextDocumentIdentifier | はい | 対象ドキュメントの識別子 |
| range | Range | はい | ヒントを取得する範囲 |

### 出力パラメータ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| inlayHints | InlayHint[] | インレイヒントのリスト |
| inlayHints[].label | InlayHintLabelPart[] | ヒントのラベル情報 |
| inlayHints[].position | Position | ヒントの表示位置 |
| inlayHints[].kind | InlayHintKind | ヒントの種類（Type, Parameter, Other） |
| inlayHints[].paddingLeft | boolean | 左側にパディングを追加するか |
| inlayHints[].paddingRight | boolean | 右側にパディングを追加するか |

## 表示項目

| 項目名 | 型 | 説明 |
|--------|-----|------|
| label.value | string | ヒントのテキスト（例：`: string`, `name:`, `await`） |
| label.tooltip | string | ツールチップ情報 |
| label.location | Location | ジャンプ先の位置情報（型定義等） |
| position | Position | 表示位置 |
| kind | InlayHintKind | Type=1, Parameter=2, Other=3 |

## イベント仕様

### 1-インレイヒント要求

1. エディタが `textDocument/inlayHint` リクエストを送信
2. サーバーが `Lua.hint.enable` 設定を確認
3. ワークスペースの準備完了を待機
4. 指定範囲内のソースコードを解析
5. 各種ヒント生成処理を実行（typeHint, paramName, awaitHint, arrayIndex, semicolonHint）
6. InlayHint配列として返却

### 2-インレイヒント解決

1. エディタが `inlayHint/resolve` リクエストを送信
2. サーバーが受け取ったヒント情報をそのまま返却（現時点では追加処理なし）

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| インレイヒント要求 | - | - | データベース操作なし（読み取り専用） |

## メッセージ仕様

| メッセージID | 種別 | 表示内容 | 発生条件 |
|-------------|------|----------|----------|
| HOVER_AWAIT_TOOLTIP | 情報 | 非同期呼び出しの説明 | awaitヒントのツールチップ |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| Lua.hint.enable が false | nullを返却 |
| ファイル状態が取得できない | nullを返却 |

## 備考

- 各種ヒントは個別の設定で有効/無効を切り替え可能：
  - `Lua.hint.paramType`: パラメータの型ヒント
  - `Lua.hint.setType`: 変数設定時の型ヒント
  - `Lua.hint.paramName`: パラメータ名ヒント（All/Literal/Disable）
  - `Lua.hint.await`: awaitヒント
  - `Lua.hint.arrayIndex`: 配列インデックスヒント（Enable/Auto/Disable）
  - `Lua.hint.semicolon`: セミコロンヒント（All/SameLine/Disable）

---

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

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

### 推奨読解順序

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

LSPプロトコルで定義されるInlayHint型とInlayHintKind型の構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | define.lua | `script/proto/define.lua` | InlayHintKind定義（Type=1, Parameter=2, Other=3）を確認 |
| 1-2 | hint.lua | `script/core/hint.lua` | 返却されるresults構造（61-67行目等）を確認 |

**読解のコツ**: InlayHintは text, offset, kind, where, source, tooltip などのフィールドを持ちます。

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

LSPリクエストハンドラがどのように呼び出されるかを理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | provider.lua | `script/provider/provider.lua` | `textDocument/inlayHint` ハンドラ（1407-1454行目）を確認 |

**主要処理フロー**:
1. **1407行目**: `m.register 'textDocument/inlayHint'` でハンドラを登録
2. **1415行目**: URIを取得
3. **1416-1418行目**: `Lua.hint.enable` 設定を確認
4. **1419行目**: ワークスペース準備完了を待機
5. **1420行目**: core/hintを呼び出し
6. **1425-1426行目**: 範囲を変換
7. **1427行目**: hint関数を実行
8. **1428-1451行目**: 結果をInlayHint配列に変換

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

各種ヒント生成処理を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | hint.lua | `script/core/hint.lua` | ヒント生成の全体フロー（332-339行目）を確認 |

**主要処理フロー**:
- **11-69行目**: typeHint - 型ヒントの生成
- **101-160行目**: paramName - パラメータ名ヒントの生成
- **163-230行目**: arrayIndex - 配列インデックスヒントの生成
- **234-260行目**: awaitHint - awaitヒントの生成
- **277-329行目**: semicolonHint - セミコロンヒントの生成
- **332-339行目**: 全ヒント生成関数の呼び出し

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

```
textDocument/inlayHint (provider.lua:1407-1454)
    │
    ├─ config.get(uri, 'Lua.hint.enable') - 設定確認
    │
    ├─ workspace.awaitReady(uri) - ワークスペース準備待機
    │
    └─ core/hint.lua (332-339行目)
           │
           ├─ typeHint(uri, results, start, finish) - 型ヒント
           │      └─ vm.getInfer(source):view(uri) - 型推論
           │
           ├─ paramName(uri, results, start, finish) - パラメータ名
           │      └─ vm.getDefs(source.node) - 定義取得
           │
           ├─ awaitHint(uri, results, start, finish) - awaitマーカー
           │      └─ vm.isAsyncCall(source) - 非同期判定
           │
           ├─ arrayIndex(uri, results, start, finish) - 配列インデックス
           │
           └─ semicolonHint(uri, results, start, finish) - セミコロン
```

### データフロー図

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

InlayHintRequest {             1. 設定確認                      InlayHint[] {
  textDocument,                2. ワークスペース準備待機           [
  range: {                     3. 範囲内ソース解析                  {
    start, end                 4. typeHint()                        label: [{ value: ': string' }],
  }                            5. paramName()                       position: {line, character},
}                              6. awaitHint()                       kind: 1 (Type)
                               7. arrayIndex()                    },
                               8. semicolonHint()                   {
                               9. InlayHint配列生成                  label: [{ value: 'name:' }],
                                                                    position: {line, character},
                                                                    kind: 2 (Parameter)
                                                                  }
                                                                ]
                                                               }
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| provider.lua | `script/provider/provider.lua` | ソース | LSPリクエストハンドラの登録・処理 |
| hint.lua | `script/core/hint.lua` | ソース | インレイヒント生成のコアロジック |
| define.lua | `script/proto/define.lua` | ソース | InlayHintKind定義 |
| vm.lua | `script/vm/vm.lua` | ソース | 型推論・定義取得 |
| config.lua | `script/config.lua` | ソース | 設定値の管理 |
| converter.lua | `script/proto/converter.lua` | ソース | LSPプロトコル型変換・位置変換 |
| guide.lua | `script/parser/guide.lua` | ソース | AST操作ユーティリティ |
