# 通知設計書 44-WINDOW_SETTING_WS_DIAGNOSTIC

## 概要

本ドキュメントは、lua-language-serverにおける「ワークスペース診断設定案内」通知（WINDOW_SETTING_WS_DIAGNOSTIC）の設計仕様を定義する。この通知は、ワークスペース診断がキャンセルされた際に、診断の遅延または無効化設定についてユーザーに案内するメッセージを表示する。

### 本通知の処理概要

この通知は、ワークスペース診断処理中にユーザーが操作をキャンセルした場合、または診断が頻繁にキャンセルされる場合に、設定変更の選択肢を提示するダイアログを表示する。

**業務上の目的・背景**：大規模なワークスペースでは診断処理に時間がかかり、ユーザーの作業を妨げる可能性がある。この通知により、ユーザーは診断の遅延実行（アイドル時実行）または完全無効化を選択でき、開発体験を改善できる。ユーザーが繰り返し診断をキャンセルする場合、設定変更を促すことでUXを向上させる。

**通知の送信タイミング**：`askForDisable`関数が呼び出された時点でダイアログが表示される。これは診断処理がキャンセルまたは中断された際のフォローアップとして機能する。`dontAskedForDisable`フラグがtrueの場合は表示されない。

**通知の受信者**：VSCode等のIDEを使用してLuaプロジェクトを編集している開発者。特に大規模プロジェクトで診断処理に時間がかかる場合に関連する。

**通知内容の概要**：「You can delay or disable workspace diagnostics in settings」（日本語：「ワークスペース設定で診断を遅延または無効化できます」）というメッセージとともに、3つの選択肢（再度表示しない、遅延診断、診断無効化）が表示される。

**期待されるアクション**：ユーザーは3つの選択肢から1つを選択する。「再度表示しない」で通知を抑止、「遅延診断」でアイドル時に診断を実行、「診断無効化」で診断を完全に停止する。

## 通知種別

LSPメッセージリクエスト（`window/showMessageRequest`）

## 送信仕様

### 基本情報

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

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

現在のワークスペースURIに対してダイアログを表示。`dontAskedForDisable`フラグで抑止制御される。

## 通知テンプレート

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

| 項目 | 内容 |
|-----|------|
| メッセージ種別 | Info |
| アクションボタン数 | 3 |
| 形式 | テキスト |

### 本文テンプレート

```
英語: You can delay or disable workspace diagnostics in settings
日本語: ワークスペース設定で診断を遅延または無効化できます
中国語(簡体): 你可以在设置中延迟或禁用工作区诊断
```

### アクションボタン

| ボタン | ラベル（英語） | ラベル（日本語） |
|-------|---------------|-----------------|
| 1 | Don't show again | 再度表示しない |
| 2 | Idle time diagnosis (delay 30 seconds) | アイドル時に診断（30秒遅延） |
| 3 | Disable workspace diagnostics | ワークスペース診断を無効にします |

### 添付ファイル

なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| delay | 遅延秒数 | 定数（30秒） | Yes（WINDOW_DELAY_WS_DIAGNOSTIC用） |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 関数呼び出し | askForDisable(uri) | dontAskedForDisable = false | 診断設定案内要求時 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| dontAskedForDisable = true | ユーザーが「再度表示しない」を選択済み |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[askForDisable呼び出し] --> B{dontAskedForDisable?}
    B -->|true| C[return - 表示しない]
    B -->|false| D[proto.awaitRequest送信]
    D --> E[ダイアログ表示]
    E --> F{ユーザー選択}
    F -->|WINDOW_DONT_SHOW_AGAIN| G[dontAskedForDisable = true]
    F -->|delayTitle| H[client.setConfig: workspaceDelay = 30000]
    F -->|WINDOW_DISABLE_DIAGNOSTIC| I[client.setConfig: workspaceDelay = -1]
    F -->|キャンセル| J[return]
    G --> K[終了]
    H --> K
    I --> K
    J --> K
```

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

### 参照テーブル一覧

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

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

### 設定参照・更新

| 設定キー | 操作 | 値 | 説明 |
|---------|------|-----|------|
| Lua.diagnostics.workspaceDelay | SET | 30000 | 遅延診断（30秒） |
| Lua.diagnostics.workspaceDelay | SET | -1 | 診断無効化 |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| m.dontAskedForDisable | SET | 再度表示しないフラグ |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| ダイアログ表示失敗 | クライアントが応答しない場合 | nilチェックで処理スキップ |
| 設定更新失敗 | client.setConfigが失敗した場合 | ログ記録、処理継続 |

### リトライ仕様

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

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 表示制限 | dontAskedForDisableフラグで制御 |

### 配信時間帯

制限なし

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

- 設定変更はローカルの設定ファイルのみに影響
- ユーザーの明示的な選択が必要
- 機密情報は含まれない

## 備考

- 遅延時間（30秒）はaskForDisable関数内で定数として定義
- WINDOW_DELAY_WS_DIAGNOSTICのテンプレート変数`{}`に遅延秒数が挿入される
- 関連する通知：WINDOW_DONT_SHOW_AGAIN、WINDOW_DELAY_WS_DIAGNOSTIC、WINDOW_DISABLE_DIAGNOSTIC

---

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

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

### 推奨読解順序

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

askForDisable関数の全体構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | diagnostic.lua | `script/provider/diagnostic.lua` | 467-512行目：askForDisable関数全体 |

**読解のコツ**: `---@async`アノテーションは非同期関数を示す。`proto.awaitRequest`はLSPリクエストを送信し、レスポンスを待機する。

#### Step 2: メッセージ構造を理解する

ダイアログのメッセージとアクション定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | diagnostic.lua | `script/provider/diagnostic.lua` | 471-487行目：ダイアログ構成 |

**主要処理フロー**:
1. **471行目**: `delay = 30` - 遅延秒数の定義
2. **472行目**: `delayTitle = lang.script('WINDOW_DELAY_WS_DIAGNOSTIC', delay)` - 遅延ボタンラベル生成
3. **473-487行目**: `proto.awaitRequest('window/showMessageRequest', ...)` - ダイアログ表示
4. **475行目**: `message = lang.script.WINDOW_SETTING_WS_DIAGNOSTIC` - メインメッセージ

#### Step 3: ユーザー選択処理を理解する

各ボタンクリック時の処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | diagnostic.lua | `script/provider/diagnostic.lua` | 491-511行目：選択処理分岐 |

**主要処理フロー**:
- **491-492行目**: `WINDOW_DONT_SHOW_AGAIN`選択時 - `dontAskedForDisable = true`
- **493-501行目**: `delayTitle`選択時 - `workspaceDelay = delay * 1000`
- **502-510行目**: `WINDOW_DISABLE_DIAGNOSTIC`選択時 - `workspaceDelay = -1`

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

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

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

```
askForDisable (diagnostic.lua:467)
    |
    +-- [dontAskedForDisableチェック] (468-470行目)
    |
    +-- lang.script('WINDOW_DELAY_WS_DIAGNOSTIC', delay) (472行目)
    |
    +-- proto.awaitRequest('window/showMessageRequest') (473行目)
    |       |
    |       +-- message: lang.script.WINDOW_SETTING_WS_DIAGNOSTIC (475行目)
    |       +-- actions: [WINDOW_DONT_SHOW_AGAIN, delayTitle, WINDOW_DISABLE_DIAGNOSTIC]
    |
    +-- [選択処理] (491-511行目)
            |
            +-- WINDOW_DONT_SHOW_AGAIN → dontAskedForDisable = true
            +-- delayTitle → client.setConfig(workspaceDelay = 30000)
            +-- WINDOW_DISABLE_DIAGNOSTIC → client.setConfig(workspaceDelay = -1)
```

### データフロー図

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

uri              ───▶  askForDisable関数
                            |
                            ▼
                       proto.awaitRequest  ───▶  ダイアログ表示
                            |                    [WINDOW_SETTING_WS_DIAGNOSTIC]
                            ▼
                       [ユーザー選択]
                            |
            ┌───────────────┼───────────────┐
            ▼               ▼               ▼
    dontAskedForDisable   client.setConfig   client.setConfig
    = true                (delay=30000)      (delay=-1)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| diagnostic.lua | `script/provider/diagnostic.lua` | ソース | 診断プロバイダー（メイン処理） |
| client.lua | `script/client.lua` | ソース | 設定変更API |
| proto.lua | `script/proto/proto.lua` | ソース | LSPプロトコル通信 |
| define.lua | `script/proto/define.lua` | ソース | MessageType定義 |
| script.lua | `locale/en-us/script.lua` | 言語リソース | 英語メッセージ定義 |
| script.lua | `locale/ja-jp/script.lua` | 言語リソース | 日本語メッセージ定義 |
