# 通知設計書 42-WINDOW_INCREASE_UPPER_LIMIT

## 概要

本ドキュメントは、lua-language-serverにおける「上限増加」ボタン通知（WINDOW_INCREASE_UPPER_LIMIT）の設計仕様を定義する。この通知は、プリロードファイル数が上限に達した際にユーザーに表示されるダイアログ内のアクションボタンのラベルとして使用される。

### 本通知の処理概要

この通知は、ワークスペース内のLuaファイルのプリロード数が設定上限（`Lua.workspace.maxPreload`）に達した際に、上限を増やすためのアクションボタンを提供する。

**業務上の目的・背景**：大規模なLuaプロジェクトでは、ワークスペース内のファイル数がデフォルトのプリロード上限を超えることがある。このボタンにより、ユーザーはワンクリックで上限を増やすことができ、全てのファイルに対する言語サービス機能（補完、定義ジャンプなど）を利用可能にする。手動で設定ファイルを編集する必要がなく、UXを向上させる。

**通知の送信タイミング**：ワークスペースのファイル読み込み処理中に、プリロードしたファイル数が`Lua.workspace.maxPreload`設定値を超えた最初の時点で、ダイアログが表示される。このダイアログのアクションボタンとして本通知のラベルが使用される。

**通知の受信者**：VSCode等のIDEを使用してLuaプロジェクトを編集している開発者。特に大規模プロジェクトで作業している開発者に関連する。

**通知内容の概要**：「Increase upper limit」（日本語：「上限を増やします」）というボタンラベルが表示される。MWS_MAX_PRELOAD通知のダイアログ内に配置される。

**期待されるアクション**：ユーザーがこのボタンをクリックすると、`Lua.workspace.maxPreload`設定値が自動的に増加（現在値 + max(1000, 現在値)）され、残りのファイルのプリロードが続行される。

## 通知種別

LSPメッセージリクエスト（`window/showMessageRequest`）のアクションボタン

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 非同期（コールバック付き） |
| 優先度 | 中（Info） |
| リトライ | なし |

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

現在のワークスペーススコープに対してダイアログを表示。スコープごとに1回のみ表示される（`hasHintedMaxPreload`フラグで制御）。

## 通知テンプレート

### メッセージダイアログの場合

| 項目 | 内容 |
|-----|------|
| メッセージ種別 | Info |
| 親メッセージ | MWS_MAX_PRELOAD |
| 形式 | テキスト |

### 本文テンプレート

```
英語: Increase upper limit
日本語: 上限を増やします
中国語(簡体): 增加上限
```

### 添付ファイル

なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| なし | ボタンラベルは固定テキスト | locale/*/script.lua | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| ファイル読み込み | mt:checkMaxPreload | preload > max かつ hasHintedMaxPreload = false | プリロード上限超過時 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| hasHintedMaxPreload = true | 既にこのスコープで通知済みの場合 |
| libraryUri が設定されている場合 | ライブラリファイルの読み込みの場合はプリロードカウントに含めない |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[loadFile呼び出し] --> B{libraryUri?}
    B -->|Yes| C[プリロードカウントせず]
    B -->|No| D[preload++]
    D --> E[checkMaxPreload呼び出し]
    E --> F{preload > max?}
    F -->|No| G[処理継続]
    F -->|Yes| H{hasHintedMaxPreload?}
    H -->|Yes| I[false返却・処理中断]
    H -->|No| J[hasHintedMaxPreload = true]
    J --> K[client.requestMessage表示]
    K --> L[WINDOW_INCREASE_UPPER_LIMITボタン表示]
    L --> M{ユーザー選択}
    M -->|クリック| N[client.setConfig呼び出し]
    N --> O[maxPreload値を増加]
    M -->|キャンセル| I
    G --> P[ファイル読み込み継続]
```

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

### 参照テーブル一覧

本通知はファイルシステムとメモリ内設定のみを使用し、データベースは使用しない。

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| N/A | N/A | データベース不使用 |

### 設定参照

| 設定キー | 用途 | デフォルト値 |
|---------|------|-------------|
| Lua.workspace.maxPreload | プリロード上限値 | 設定による |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| scope | SET | hasHintedMaxPreloadフラグ設定 |
| config | SET | Lua.workspace.maxPreload値更新 |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 設定更新失敗 | client.setConfigが失敗した場合 | ログ記録、ユーザーに手動設定を促す |
| ダイアログ表示失敗 | クライアントが応答しない場合 | タイムアウト後に処理継続 |

### リトライ仕様

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

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| スコープあたり上限 | 1回（hasHintedMaxPreloadで制御） |

### 配信時間帯

制限なし（ファイル読み込み時に即座に表示）

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

- 設定変更はローカルの設定ファイルのみに影響
- ユーザーの明示的なクリックアクションが必要
- 機密情報は含まれない

## 備考

- 上限増加量は`max + max(1000, max)`で計算される（最低1000ファイル増加）
- ボタンのindex = 1で選択を判定している

---

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

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

### 推奨読解順序

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

workspace.loadingモジュールの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | loading.lua | `script/workspace/loading.lua` | 10-24行目：`workspace.loading`クラスとフィールド定義 |

**読解のコツ**: `mt._loadLock`、`mt.read`、`mt.max`、`mt.preload`などのフィールドがファイル読み込み状態を管理している。

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

プリロード上限チェックの処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | loading.lua | `script/workspace/loading.lua` | 36-64行目：`mt:checkMaxPreload`関数 |

**主要処理フロー**:
1. **37行目**: `config.get(uri, 'Lua.workspace.maxPreload')`で現在の上限取得
2. **38-40行目**: 上限内であれば`true`返却
3. **41-43行目**: 既に通知済みなら`false`返却
4. **44行目**: `hasHintedMaxPreload`フラグを`true`に設定
5. **45-62行目**: `client.requestMessage`でダイアログ表示

#### Step 3: ボタンクリック時の処理を理解する

設定変更処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | loading.lua | `script/workspace/loading.lua` | 50-60行目：コールバック関数 |
| 3-2 | client.lua | `script/client.lua` | 119-145行目：`m.requestMessage`関数 |

**主要処理フロー**:
- **51行目**: `index == 1`でボタンクリックを判定
- **52-59行目**: `client.setConfig`で`Lua.workspace.maxPreload`を更新
- **57行目**: 新しい値は`max + math.max(1000, max)`

#### Step 4: 言語リソースを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | script.lua | `locale/en-us/script.lua` | 552-553行目：英語メッセージ |
| 4-2 | script.lua | `locale/ja-jp/script.lua` | 552-553行目：日本語メッセージ |

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

```
mt:loadFile (loading.lua:69)
    |
    +-- [preload カウント増加] (72行目)
    |
    +-- mt:checkMaxPreload (loading.lua:36)
            |
            +-- config.get('Lua.workspace.maxPreload')
            |
            +-- scp:get('hasHintedMaxPreload')
            |
            +-- scp:set('hasHintedMaxPreload', true)
            |
            +-- client.requestMessage (client.lua:119)
                    |
                    +-- proto.request('window/showMessageRequest')
                    |
                    +-- [コールバック: ボタンクリック時]
                            |
                            +-- client.setConfig (client.lua:202+)
```

### データフロー図

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

maxPreload設定値  ───▶  checkMaxPreload判定
preloadカウント   ───▶       |
                             ▼
                     client.requestMessage  ───▶  ダイアログ表示
                             |                    [WINDOW_INCREASE_UPPER_LIMIT]
                             ▼
                     [ユーザークリック]     ───▶  client.setConfig
                                                      |
                                                      ▼
                                              設定ファイル更新
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| loading.lua | `script/workspace/loading.lua` | ソース | ワークスペースファイル読み込み管理 |
| client.lua | `script/client.lua` | ソース | LSPクライアント通信 |
| script.lua | `locale/en-us/script.lua` | 言語リソース | 英語メッセージ定義 |
| script.lua | `locale/ja-jp/script.lua` | 言語リソース | 日本語メッセージ定義 |
| proto.lua | `script/proto/proto.lua` | ソース | LSPプロトコル通信 |
| define.lua | `script/proto/define.lua` | ソース | メッセージタイプ定義 |
