# 通知設計書 38-WINDOW_PROCESSING_SEMANTIC_FULL

## 概要

本ドキュメントは、Lua Language Serverにおける「セマンティックカラーリング（フル）処理中」通知（WINDOW_PROCESSING_SEMANTIC_FULL）の設計を記載する。

### 本通知の処理概要

この通知は、ユーザーがエディタ上でファイル全体のセマンティックトークン（シンタックスハイライト）を処理している際に、Language Serverがその処理を実行中であることをユーザーに視覚的に伝えるための進捗表示通知である。

**業務上の目的・背景**：セマンティックカラーリングは、コードの意味を解析してより正確なシンタックスハイライトを提供する機能である。変数の種類（ローカル、グローバル、パラメータ等）やアノテーション情報に基づいて色分けを行う。大きなファイルでは全体の解析に時間がかかることがある。この通知により、ユーザーは処理が進行中であることを把握できる。

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

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

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

**期待されるアクション**：ユーザーは処理完了を待ち、エディタ上でより正確なシンタックスハイライトが適用されるのを確認する。

## 通知種別

LSP進捗通知（window/workDoneProgress）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 非同期 |
| 優先度 | 中 |
| リトライ | なし |

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

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

## 通知テンプレート

### LSP進捗通知

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

### 本文テンプレート

```
セマンティックカラーリング（フール）を処理しています...
```

英語版:
```
Processing full semantic tokens...
```

### 添付ファイル

なし

## テンプレート変数

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

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| LSPリクエスト | textDocument/semanticTokens/full | 処理開始から0.5秒経過 | ファイル全体のセマンティックトークンリクエスト受信時 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| 処理時間が0.5秒未満 | 短時間で完了した場合は表示しない |
| progressBar設定がfalse | ユーザーが進捗バーを無効化している場合 |
| useSemanticByRangeオプションがtrue | クライアントがrange方式を使用する場合 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[textDocument/semanticTokens/fullリクエスト受信] --> B[workspace.awaitReady]
    B --> C[progress.create呼び出し]
    C --> D{0.5秒経過?}
    D -->|Yes| E[window/workDoneProgress/create送信]
    E --> F[$/progress begin通知]
    F --> G[セマンティック解析処理]
    G --> H{処理完了?}
    H -->|Yes| I[$/progress end通知]
    H -->|No| J[$/progress report通知]
    J --> G
    I --> K[トークンデータ返却]
    D -->|No| L{処理完了?}
    L -->|Yes| K
    L -->|No| D
```

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

### 参照テーブル一覧

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

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

該当なし

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| セマンティック無効 | Lua.semantic.enable設定がfalse | 空の結果を返却 |
| ファイル未読込 | 対象ファイルのAST取得失敗 | 空の結果を返却 |

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

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

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

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

## 備考

- 進捗表示の遅延時間（0.5秒）は固定値で、設定変更不可
- クライアントのuseSemanticByRangeオプションにより、full方式とrange方式が切り替わる
- ファイル全体（0からmath.huge）を処理対象とする
- セマンティックトークンはLSP仕様に基づくエンコード形式で返却される

---

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

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

### 推奨読解順序

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

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

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

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

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

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

**主要処理フロー**:
1. **1079-1109行目**: `client.event`内での条件付き登録
2. **1082-1106行目**: `textDocument/semanticTokens/full`メソッドの登録
3. **1099行目**: `progress.create(uri, lang.script.WINDOW_PROCESSING_SEMANTIC_FULL, 0.5)`で進捗オブジェクト作成
4. **1101行目**: `core.semantic-tokens`モジュールを呼び出してセマンティック解析

#### Step 3: セマンティックトークンコアロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | semantic-tokens.lua | `script/core/semantic-tokens.lua` | セマンティックトークンのメインロジック |

**主要処理フロー**:
- **873-920行目**: メイン関数。セマンティックトークンを生成
- **12-728行目**: Care switchで各ソースタイプに応じたトークン生成
- **730-769行目**: buildTokens関数でLSP形式のトークンエンコード

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

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

**主要処理フロー**:
- **544-545行目**: `WINDOW_PROCESSING_SEMANTIC_FULL`の日本語定義

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

```
textDocument/semanticTokens/full (provider.lua:1082-1106)
    │
    ├─ workspace.awaitReady(uri)
    │      └─ ワークスペース準備待機
    │
    ├─ progress.create(uri, title, delay)  (progress.lua:155-168)
    │      └─ 進捗オブジェクト生成
    │          └─ update() → window/workDoneProgress/create
    │                      → $/progress (begin/report/end)
    │
    └─ core.semantic-tokens(uri, start, finish)  (semantic-tokens.lua:873-920)
           ├─ config.get('Lua.semantic.enable') - 有効性チェック
           ├─ files.getState() - AST取得
           ├─ guide.eachSourceBetween() - ソース走査
           │    └─ Care() - 各ソースタイプの処理
           │         ├─ getglobal/setglobal
           │         ├─ local/setlocal
           │         ├─ field/method
           │         └─ doc.* (アノテーション)
           └─ buildTokens() - LSP形式エンコード
```

### データフロー図

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

textDocument/            provider.lua                   SemanticTokens
  semanticTokens/full ─▶ ├─ progress.create() ───▶     {data: number[]}
  リクエスト              │    └─ 進捗通知
    │                    ├─ semantic-tokens.lua
    │                    │    ├─ Care() - トークン生成
    │                    │    └─ buildTokens()
    │                    └─ 結果返却
    │
    └── params:          進捗通知:                      トークンデータ:
        └─ textDocument   ├─ $/progress (begin)         エンコード済み配列
            └─ uri        ├─ $/progress (report)        [deltaLine,
                          └─ $/progress (end)            deltaStart,
                                                          length,
                                                          tokenType,
                                                          tokenModifiers]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| provider.lua | `script/provider/provider.lua` | ソース | LSPリクエストハンドラ |
| progress.lua | `script/progress.lua` | ソース | 進捗管理モジュール |
| semantic-tokens.lua | `script/core/semantic-tokens.lua` | ソース | セマンティックトークンコアロジック |
| define.lua | `script/proto/define.lua` | ソース | TokenTypes/TokenModifiers定義 |
| script.lua | `locale/ja-jp/script.lua` | ローカライズ | 日本語メッセージ |
| script.lua | `locale/en-us/script.lua` | ローカライズ | 英語メッセージ |
