# 通知設計書 41-WINDOW_PROCESSING_BUILD_META

## 概要

本ドキュメントは、lua-language-serverにおける「メタデータ処理中」通知（WINDOW_PROCESSING_BUILD_META）の設計仕様を定義する。この通知は、コンパイラのメタデータビルド処理中の進捗状況をユーザーに表示するためのプログレスバー通知である。

### 本通知の処理概要

この通知は、外部APIのメタデータ（型定義ファイル）をビルドする際に、処理の進捗状況をIDEのプログレスバーとして表示する機能を提供する。

**業務上の目的・背景**：Unity、Love2Dなどの外部フレームワークやライブラリのAPIドキュメントからLuaの型定義メタファイルを生成する処理は時間がかかる場合がある。この通知により、ユーザーは処理が正常に進行していることを視覚的に確認でき、処理完了を待つ間の不安を軽減できる。また、処理が停止した場合の問題検知にも役立つ。

**通知の送信タイミング**：メタファイルビルド処理（`m.build`関数）が開始され、0.5秒以上経過した時点でプログレスバーが表示される。各クラスの処理ごとに進捗が更新され、全クラスの処理完了時に自動的に終了する。

**通知の受信者**：LSPクライアント（VSCode等のIDE）を通じてエディタを使用している開発者が受信者となる。

**通知内容の概要**：「Processing build meta...」（日本語：「コンパイラのメタデータを処理しています...」）というタイトルとともに、現在処理中の名前空間名と進捗率（パーセンテージ）が表示される。

**期待されるアクション**：受信者は処理完了を待つ。処理が長時間停止する場合は、問題の調査やLSPサーバーの再起動を検討する。

## 通知種別

LSPプログレスバー通知（`$/progress`）

## 送信仕様

### 基本情報

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

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

LSPクライアントに対して`$/progress`通知として送信される。`Lua.window.progressBar`設定が有効な場合にのみ表示される。

## 通知テンプレート

### プログレスバー通知の場合

| 項目 | 内容 |
|-----|------|
| 通知種別 | LSP Progress |
| タイトル | WINDOW_PROCESSING_BUILD_META |
| 形式 | テキスト |

### 本文テンプレート

```
英語: Processing build meta...
日本語: コンパイラのメタデータを処理しています...
中国語(簡体): 正在处理元数据...
```

### 添付ファイル

なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| message | 現在処理中の名前空間名 | class.namespace または api.root | Yes |
| percentage | 処理進捗率(0-100) | i / #api.classes * 100 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| API呼び出し | m.build関数実行 | Lua.window.progressBar設定が有効 | 外部APIメタファイルビルド時 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| Lua.window.progressBar = false | 設定でプログレスバーが無効化されている場合 |
| 処理時間が0.5秒未満 | 遅延表示設定により短時間の処理では表示されない |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[m.build関数呼び出し] --> B[progress.create呼び出し]
    B --> C{0.5秒経過?}
    C -->|No| D[バッファリング継続]
    C -->|Yes| E[window/workDoneProgress/create送信]
    E --> F[$/progress begin送信]
    F --> G[クラス処理ループ開始]
    G --> H[setMessage: 名前空間名]
    H --> I[setPercentage: 進捗率]
    I --> J[$/progress report送信]
    J --> K{全クラス処理完了?}
    K -->|No| G
    K -->|Yes| L[$/progress end送信]
    L --> M[プログレス削除]
    M --> N[終了]
    D --> G
```

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

### 参照テーブル一覧

本通知はファイルシステムベースの処理であり、データベースは使用しない。

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

### 更新テーブル一覧

データベースの更新は行わない。

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 送信失敗 | LSPクライアントが切断された場合 | ログ記録のみ、処理は継続 |
| テンプレートエラー | 言語リソースが見つからない場合 | デフォルト（英語）にフォールバック |

### リトライ仕様

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

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 更新間隔 | 最小50ms（time.time()による制御） |
| バースト制限 | なし |

### 配信時間帯

制限なし（処理実行時に即座に送信）

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

- 通知内容には名前空間名のみが含まれ、機密情報は含まれない
- LSP通信はクライアント-サーバー間のローカル通信であり、外部ネットワークには送信されない

## 備考

- プログレスバーの表示遅延（0.5秒）は、短時間で完了する処理に対してUIの点滅を防ぐための設計
- `<close>`アノテーションにより、関数終了時に自動的にプログレスバーが削除される

---

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

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

### 推奨読解順序

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

メタファイルビルドで使用されるデータ構造（meta、meta.class等）を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | build-meta.lua | `script/provider/build-meta.lua` | 8-35行目：`@class meta`、`@class meta.class`等の型定義を確認 |

**読解のコツ**: Luaの`---@class`アノテーションはEmmyLua形式の型定義。`---@field`で各フィールドの型を定義している。

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

メタファイルビルドの起点となる`m.build`関数を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | build-meta.lua | `script/provider/build-meta.lua` | 127-151行目：`m.build`関数の全体構造 |

**主要処理フロー**:
1. **130行目**: `m.build(path, api)`関数定義開始
2. **138行目**: `progress.create(nil, lang.script.WINDOW_PROCESSING_BUILD_META, 0.5)` - プログレスバー作成
3. **139-146行目**: クラス処理ループでプログレス更新
4. **148-150行目**: ファイル出力処理

#### Step 3: プログレス管理を理解する

progressモジュールの動作を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | progress.lua | `script/progress.lua` | 13-27行目：progressオブジェクトの構造 |
| 3-2 | progress.lua | `script/progress.lua` | 155-168行目：`m.create`関数 |
| 3-3 | progress.lua | `script/progress.lua` | 81-133行目：`mt:update`関数 - LSP通知送信ロジック |

**主要処理フロー**:
- **92行目**: `config.get(self._uri, 'Lua.window.progressBar')`で設定確認
- **95-97行目**: `proto.request('window/workDoneProgress/create')`でトークン作成
- **98-107行目**: `proto.notify('$/progress')`でbegin通知送信
- **124-131行目**: `proto.notify('$/progress')`でreport通知送信

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

多言語対応のメッセージ定義を理解する。

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

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

```
m.build (build-meta.lua:130)
    |
    +-- progress.create (progress.lua:155)
    |       |
    |       +-- mt:update (progress.lua:81) [遅延後]
    |               |
    |               +-- proto.request('window/workDoneProgress/create')
    |               +-- proto.notify('$/progress', {kind='begin'})
    |
    +-- [クラス処理ループ]
    |       |
    |       +-- proc:setMessage (progress.lua:55)
    |       +-- proc:setPercentage (progress.lua:66)
    |               |
    |               +-- mt:update (progress.lua:81)
    |                       |
    |                       +-- proto.notify('$/progress', {kind='report'})
    |
    +-- proc:__close (progress.lua:135) [<close>による自動呼び出し]
            |
            +-- mt:remove (progress.lua:30)
                    |
                    +-- proto.notify('$/progress', {kind='end'})
```

### データフロー図

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

meta API定義     ───▶  build-meta.lua            ───▶  メタファイル(.lua)
(classes配列)           |
                        +-- progress.lua          ───▶  LSP $/progress通知
                              |
                              +-- proto.lua       ───▶  JSONRPCメッセージ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| build-meta.lua | `script/provider/build-meta.lua` | ソース | メタファイルビルドのメイン処理 |
| progress.lua | `script/progress.lua` | ソース | プログレスバー管理 |
| proto.lua | `script/proto/proto.lua` | ソース | LSPプロトコル通信 |
| script.lua | `locale/en-us/script.lua` | 言語リソース | 英語メッセージ定義 |
| script.lua | `locale/ja-jp/script.lua` | 言語リソース | 日本語メッセージ定義 |
| define.lua | `script/proto/define.lua` | ソース | LSPプロトコル定数定義 |
