# 通知設計書 40-WINDOW_PROCESSING_HINT

## 概要

本ドキュメントは、Lua Language Serverにおける「インラインヒント処理中」通知（WINDOW_PROCESSING_HINT）の設計を記載する。

### 本通知の処理概要

この通知は、ユーザーがエディタ上でインラインヒント（型ヒント、パラメータ名ヒント等）を処理している際に、Language Serverがその処理を実行中であることをユーザーに視覚的に伝えるための進捗表示通知である。

**業務上の目的・背景**：インラインヒントは、コード内に型情報やパラメータ名を直接表示する機能である。変数の型、関数パラメータの名前、await呼び出しの有無などを表示する。複雑なファイルでは解析に時間がかかることがある。

**通知の送信タイミング**：`textDocument/inlayHint` LSPリクエストを受信し、処理を開始してから0.5秒（500ミリ秒）経過後も処理が継続している場合に進捗バーが表示される予定である。

**現在の実装状態**：ロケールファイルにメッセージ定義は存在するが、現在のprovider.luaの`textDocument/inlayHint`ハンドラでは`progress.create`が使用されていない。この通知は将来の使用に備えて予約されているか、別のコンテキストで使用される可能性がある。

**通知の受信者**：LSPクライアント（VSCode等のエディタ）が受信し、ステータスバーや進捗インジケーターとしてユーザーに表示される。

**通知内容の概要**：「インラインヒントを処理しています...」というメッセージが表示される。日本語ロケールの場合は日本語で、それ以外の場合は各言語に対応したメッセージが表示される。

**期待されるアクション**：ユーザーは処理完了を待ち、エディタ上でインラインヒントが表示されるのを確認する。

## 通知種別

LSP進捗通知（window/workDoneProgress）- 定義済み・現在未使用

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 非同期（予定） |
| 優先度 | 中 |
| リトライ | なし |
| 実装状態 | メッセージ定義のみ（ハンドラ未実装） |

### 送信先決定ロジック

LSPクライアントに対して一律送信。進捗バーの表示は `Lua.window.progressBar` 設定に依存する（予定）。

## 通知テンプレート

### LSP進捗通知

| 項目 | 内容 |
|-----|------|
| プロトコル | LSP `$/progress` |
| トークン | 自動生成される一意のトークン |
| 種別 | begin / report / end |

### 本文テンプレート

```
インラインヒントを処理しています...
```

英語版:
```
Processing inline hint...
```

### 添付ファイル

なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| title | 進捗タイトル | lang.script.WINDOW_PROCESSING_HINT | Yes |
| percentage | 進捗率 | 処理状況 | No |
| message | 追加メッセージ | 処理内容 | No |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| LSPリクエスト | textDocument/inlayHint | 処理開始から0.5秒経過（予定） | インラインヒントリクエスト受信時 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| 処理時間が0.5秒未満 | 短時間で完了した場合は表示しない（予定） |
| progressBar設定がfalse | ユーザーが進捗バーを無効化している場合 |
| ヒント機能が無効 | Lua.hint.enable設定がfalse |

## 処理フロー

### 送信フロー（予定）

```mermaid
flowchart TD
    A[textDocument/inlayHintリクエスト受信] --> B{ヒント有効?}
    B -->|No| Z[nil返却]
    B -->|Yes| C[workspace.awaitReady]
    C --> D[progress.create呼び出し - 現在未実装]
    D --> E{0.5秒経過?}
    E -->|Yes| F[window/workDoneProgress/create送信]
    F --> G[$/progress begin通知]
    G --> H[ヒント生成処理]
    H --> I{処理完了?}
    I -->|Yes| J[$/progress end通知]
    I -->|No| K[$/progress report通知]
    K --> H
    J --> L[ヒントデータ返却]
    E -->|No| M{処理完了?}
    M -->|Yes| L
    M -->|No| E
```

### 現在の実装フロー

```mermaid
flowchart TD
    A[textDocument/inlayHintリクエスト受信] --> B{ヒント有効?}
    B -->|No| Z[nil返却]
    B -->|Yes| C[workspace.awaitReady]
    C --> D[core.hint呼び出し]
    D --> E[ヒント結果を変換]
    E --> F[ヒントデータ返却]
```

## データベース参照・更新仕様

### 参照テーブル一覧

本通知はデータベースを使用しない。ファイルシステム上のソースコードを解析する。

### テーブル別参照項目詳細

該当なし

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| ヒント無効 | Lua.hint.enable設定がfalse | nilを返却 |
| ファイル未読込 | 対象ファイルのAST取得失敗 | nilを返却 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0回（リトライなし） |
| リトライ間隔 | - |
| リトライ対象エラー | - |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | 制限なし |
| 1日あたり上限 | 制限なし |

### 配信時間帯

制限なし（リアルタイム通知）

## セキュリティ考慮事項

- 進捗通知には機密情報を含めない
- コード内容は通知メッセージに含まれない

## 備考

- メッセージ定義はロケールファイルに存在するが、現在のtextDocument/inlayHintハンドラではprogress.createが使用されていない
- 将来のバージョンで進捗表示が実装される可能性がある
- インラインヒントには以下の種類がある：
  - 型ヒント（typeHint）
  - パラメータ名ヒント（paramName）
  - await呼び出しヒント（awaitHint）
  - 配列インデックスヒント（arrayIndex）
  - セミコロンヒント（semicolonHint）

---

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

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

### 推奨読解順序

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

まず、進捗管理に関するデータ構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | progress.lua | `script/progress.lua` | 進捗オブジェクトの構造 |

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

処理の起点となるプロバイダーファイルを特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | provider.lua | `script/provider/provider.lua` | textDocument/inlayHintハンドラの登録と実装 |

**主要処理フロー**:
1. **1407-1454行目**: `textDocument/inlayHint`メソッドの登録
2. **1416-1417行目**: `Lua.hint.enable`設定チェック
3. **1419行目**: `workspace.awaitReady`でワークスペース準備待機
4. **1420行目**: `core.hint`モジュールを呼び出してヒント生成
5. 注意: **progress.createは現在使用されていない**

#### Step 3: インラインヒントコアロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | hint.lua | `script/core/hint.lua` | インラインヒントのメインロジック |

**主要処理フロー**:
- **332-340行目**: メイン関数。各種ヒントを生成
- **11-69行目**: typeHint関数で型ヒントを生成
- **100-177行目**: paramName関数でパラメータ名ヒントを生成
- **234-260行目**: awaitHint関数でawait呼び出しヒントを生成
- **179-231行目**: arrayIndex関数で配列インデックスヒントを生成
- **277-329行目**: semicolonHint関数でセミコロンヒントを生成

#### Step 4: ローカライズを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | script.lua | `locale/ja-jp/script.lua` | 日本語メッセージ定義 |

**主要処理フロー**:
- **548-549行目**: `WINDOW_PROCESSING_HINT`の日本語定義

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

```
textDocument/inlayHint (provider.lua:1407-1454)
    │
    ├─ config.get(uri, 'Lua.hint.enable')
    │      └─ ヒント機能有効性チェック
    │
    ├─ workspace.awaitReady(uri)
    │      └─ ワークスペース準備待機
    │
    ├─ [未実装] progress.create(uri, title, delay)
    │      └─ 進捗オブジェクト生成（将来予定）
    │
    ├─ files.getState(uri)
    │      └─ ファイルのAST取得
    │
    └─ core.hint(uri, start, finish)  (hint.lua:332-340)
           ├─ typeHint() - 型ヒント生成
           │    └─ vm.getInfer():view() - 型推論
           ├─ paramName() - パラメータ名ヒント生成
           │    └─ vm.getDefs() - 定義取得
           ├─ awaitHint() - await呼び出しヒント生成
           │    └─ vm.isAsyncCall() - 非同期判定
           ├─ arrayIndex() - 配列インデックスヒント生成
           └─ semicolonHint() - セミコロンヒント生成
```

### データフロー図

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

textDocument/            provider.lua                   InlayHint[]
  inlayHint ───────────▶ ├─ hint有効性チェック          [{label, position,
  リクエスト              ├─ workspace.awaitReady()       kind, paddingLeft,
    │                    ├─ hint.lua                     paddingRight}]
    │                    │    ├─ typeHint()
    │                    │    ├─ paramName()
    │                    │    ├─ awaitHint()
    │                    │    ├─ arrayIndex()
    │                    │    └─ semicolonHint()
    │                    └─ 結果変換
    │
    └── params:          進捗通知:                      ヒント:
        ├─ textDocument   （現在未実装）                  ├─ label
        │   └─ uri                                        │   ├─ value
        └─ range                                          │   ├─ tooltip
            ├─ start                                      │   └─ location
            └─ end                                        ├─ position
                                                          ├─ kind
                                                          ├─ paddingLeft
                                                          └─ paddingRight
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| provider.lua | `script/provider/provider.lua` | ソース | LSPリクエストハンドラ |
| progress.lua | `script/progress.lua` | ソース | 進捗管理モジュール（将来使用予定） |
| hint.lua | `script/core/hint.lua` | ソース | インラインヒントコアロジック |
| define.lua | `script/proto/define.lua` | ソース | InlayHintKind定義 |
| script.lua | `locale/ja-jp/script.lua` | ローカライズ | 日本語メッセージ |
| script.lua | `locale/en-us/script.lua` | ローカライズ | 英語メッセージ |
