# 通知設計書 69-WINDOW_CONVERT_CONFIG_LUA

## 概要

本ドキュメントは、Lua Language Server における `WINDOW_CONVERT_CONFIG_LUA` 通知の設計仕様を定義する。この通知は、サードパーティライブラリの設定ファイル`config.lua`を`config.json`に変換する操作を実行するためのボタンラベルとして使用される。

### 本通知の処理概要

**業務上の目的・背景**：Lua Language Serverのサードパーティライブラリ機能では、各ライブラリの設定を定義するために設定ファイルを使用する。`config.lua`形式は非推奨となり、`config.json`形式への移行が推奨されている。本通知は、`WINDOW_CONFIG_LUA_DEPRECATED`警告メッセージと組み合わせて表示され、ユーザーがワンクリックで設定ファイル形式を変換できるようにするためのボタンラベルとして使用される。

**通知の送信タイミング**：サードパーティライブラリの設定読み込み時に、`config.lua`が検出された際に、`WINDOW_CONFIG_LUA_DEPRECATED`メッセージとともにボタンとして表示される。

**通知の受信者**：IDEやエディタを使用している開発者（ユーザー）に対して、ダイアログのボタンとして表示される。

**通知内容の概要**：「config.jsonに変換」という意味のボタンラベル。

**期待されるアクション**：ユーザーがこのボタンをクリックすると、`config.lua`の内容が自動的に`config.json`形式に変換され、元の`config.lua`は削除される。

## 通知種別

アプリ内通知（LSP window/showMessageRequestの選択肢ボタン）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 非同期（ユーザー入力待ち） |
| 優先度 | 中（Info） |
| リトライ | 無 |

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

LSPプロトコルを通じて、接続中のクライアント（IDE/エディタ）に直接送信される。

## 通知テンプレート

### メール通知の場合

該当なし（LSP通知のみ）

### 本文テンプレート

英語:
```
Convert to `config.json`
```

日本語:
```
`config.json` に変換します
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| なし | テンプレート変数は使用されない | - | - |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 内部処理 | サードパーティライブラリ設定読み込み | config.jsonが存在せず、config.luaが存在する場合 | loadSingle3rdConfig関数で検出 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| config.json存在 | config.jsonが存在する場合は送信されない |
| config.lua不存在 | config.luaも存在しない場合は送信されない |
| jsonbuf生成失敗 | JSON変換に失敗した場合はボタンが機能しない |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[loadSingle3rdConfig呼び出し] --> B[loadSingle3rdConfigFromJson]
    B --> C{config.json存在?}
    C -->|Yes| D[JSON設定を返す]
    C -->|No| E[loadSingle3rdConfigFromLua]
    E --> F{config.lua存在?}
    F -->|No| G[nil返却]
    F -->|Yes| H[Lua設定読み込み]
    H --> I[jsonb.beautifyでJSON変換]
    I --> J[client.requestMessage]
    J --> K[WINDOW_CONFIG_LUA_DEPRECATEDとWINDOW_CONVERT_CONFIG_LUA表示]
    K --> L{WINDOW_CONVERT_CONFIG_LUA選択?}
    L -->|Yes| M{jsonbuf有効?}
    M -->|Yes| N[fsu.saveFileでconfig.json保存]
    N --> O[fsu.fileRemoveでconfig.lua削除]
    M -->|No| P[処理続行]
    L -->|No| P
    O --> P
    D --> P
    G --> P
```

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

### 参照テーブル一覧

該当なし（データベースは使用しない）

### 更新テーブル一覧

該当なし（ファイルシステムへの書き込み）

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| JSON変換失敗 | jsonb.beautifyが失敗した場合 | jsonbufがnilとなり、ボタンクリック時に処理されない |
| ファイル書き込み失敗 | 権限不足やディスク容量不足 | エラーログを出力 |
| ファイル削除失敗 | 権限不足やファイルロック | エラーログを出力 |

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

制限なし（随時送信）

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

- ファイル書き込みと削除を伴う操作であり、ユーザーの明示的なボタンクリックを要する
- 変換処理はjsonb.beautifyによる安全なJSON変換のみ
- 元のconfig.luaは削除されるため、必要に応じてバックアップを推奨

## 備考

- `WINDOW_CONFIG_LUA_DEPRECATED`メッセージと組み合わせて表示される
- JSON変換はjsonb.beautify関数で行われ、読みやすいインデント付きJSON形式で出力される
- 変換後、元のconfig.luaは自動的に削除される
- jsonbufがnilの場合（変換失敗）、ボタンクリック時に処理は実行されない

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | library.lua | `script/library.lua` | config.luaからconfig.jsonへの変換対象となるデータ構造を理解する |

**読解のコツ**: loadSingle3rdConfigFromLuaで読み込まれるcfgオブジェクトの構造を確認

#### Step 2: 設定読み込みと変換ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | library.lua | `script/library.lua` | loadSingle3rdConfig関数（340-383行目）が設定読み込みの起点 |

**主要処理フロー**:
1. **341行**: loadSingle3rdConfigFromJsonを試行
2. **342-343行**: 失敗時にloadSingle3rdConfigFromLuaを試行
3. **347行**: jsonb.beautify(cfg)でJSON形式に変換
4. **348-355行**: ダイアログ表示と変換処理

#### Step 3: ボタン処理ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | library.lua | `script/library.lua` | 348-355行目でボタンクリック時の処理を理解する |

**主要処理フロー**:
- **349行**: WINDOW_CONVERT_CONFIG_LUAがボタンラベルとして設定される
- **350行**: index == 1（最初のボタン=WINDOW_CONVERT_CONFIG_LUA）の場合に処理実行
- **351行**: fsu.saveFileでconfig.jsonを保存
- **352行**: fsu.fileRemoveでconfig.luaを削除

#### Step 4: 多言語対応を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | script.lua | `locale/en-us/script.lua` | 611-612行目で英語メッセージテンプレートを確認 |
| 4-2 | script.lua | `locale/ja-jp/script.lua` | 611-612行目で日本語メッセージテンプレートを確認 |

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

```
load3rdConfig (404行)
    |
    └─ load3rdConfigInDir (387行)
           |
           └─ loadSingle3rdConfig (340行)
                  |
                  ├─ loadSingle3rdConfigFromJson (341行)
                  |      └─ (成功時) config返却
                  |
                  └─ loadSingle3rdConfigFromLua (343行)
                         |
                         ├─ jsonb.beautify (347行)
                         |
                         └─ client.requestMessage (348行)
                                |
                                ├─ WINDOW_CONFIG_LUA_DEPRECATED
                                |
                                └─ WINDOW_CONVERT_CONFIG_LUA (349行)
                                       |
                                       └─ callback (350行)
                                              |
                                              ├─ fsu.saveFile (351行)
                                              |
                                              └─ fsu.fileRemove (352行)
```

### データフロー図

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

config.lua         ───▶  loadSingle3rdConfigFromLua  ───▶  cfg（Luaテーブル）
                           |
                           v
                    jsonb.beautify(cfg)
                           |
                           v
                    jsonbuf（JSON文字列）
                           |
                           v
            WINDOW_CONVERT_CONFIG_LUA選択
                           |
                           v
                    fsu.saveFile(config.json, jsonbuf) ───▶ config.json作成
                           |
                           v
                    fsu.fileRemove(config.lua) ───▶ config.lua削除
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| library.lua | `script/library.lua` | ソース | サードパーティライブラリ設定読み込みと変換 |
| client.lua | `script/client.lua` | ソース | メッセージリクエスト送信 |
| json-beautify.lua | 外部ライブラリ | ソース | JSON形式変換（jsonb.beautify） |
| fs-utility.lua | `script/fs-utility.lua` | ソース | ファイル操作（saveFile、fileRemove） |
| script.lua | `locale/en-us/script.lua` | ローカライズ | 英語メッセージテンプレート |
| script.lua | `locale/ja-jp/script.lua` | ローカライズ | 日本語メッセージテンプレート |
