# 通知設計書 81-CLI_CHECK_PROGRESS

## 概要

本ドキュメントは、Lua Language Serverのコマンドライン診断機能における「診断進捗」通知（CLI_CHECK_PROGRESS）の設計を記載する。

### 本通知の処理概要

CLI_CHECK_PROGRESSは、コマンドライン診断（--checkオプション）の実行中に、リアルタイムで診断の進捗状況をユーザーに通知するためのメッセージである。

**業務上の目的・背景**：コマンドラインでの診断処理は、大規模なワークスペースを対象とする場合に長時間を要することがある。ユーザーが処理の進行状況を把握できないと、処理が停止しているのか進行中なのか判断できず、不安を感じる可能性がある。本通知により、現在発見された問題数とファイル数をリアルタイムで表示し、診断が正常に進行していることをユーザーに伝える。

**通知の送信タイミング**：診断処理中、約0.2秒ごとにコンソールに進捗が更新される。各ファイルの診断が完了するたびに、累計の問題数と問題が発見されたファイル数がカウントされ、プログレスバーと共に表示される。

**通知の受信者**：コマンドラインで`--check`オプションを実行しているユーザー。標準出力（コンソール）に直接表示される。

**通知内容の概要**：「{問題数} ファイルに渡り、{問題数} 個の問題が発見されました」という形式で、現在の診断進捗を示す。英語では「Found {count} problems in {files} files」と表示される。

**期待されるアクション**：ユーザーは通知を確認し、診断が正常に進行していることを認識する。問題が多数発見されている場合は、診断完了後にコードの修正を検討する。

## 通知種別

コンソール出力（CLI標準出力）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（リアルタイム更新） |
| 優先度 | 中 |
| リトライ | なし |

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

コマンドラインで診断を実行しているプロセスの標準出力に直接出力される。QUIETモードが有効でない場合、かつ複数ワーカーモードでない場合にのみ表示される。

## 通知テンプレート

### コンソール出力の場合

| 項目 | 内容 |
|-----|------|
| 出力先 | 標準出力（stdout） |
| 形式 | プレーンテキスト |

### 本文テンプレート

```
日本語:
{問題数} ファイルに渡り、{問題数} 個の問題が発見されました

英語:
Found {errors} problems in {filesWithErrors} files
```

### 添付ファイル

なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| errors | 発見された診断問題の総数 | results テーブルから集計 | Yes |
| filesWithErrors | 問題が発見されたファイル数 | results テーブルのキー数 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| CLI実行 | 診断ファイル処理中 | 前回表示から0.2秒以上経過、かつ問題が1件以上発見されている場合 | プログレスバー更新時に表示 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| QUIET=true | 静音モードが有効な場合は表示しない |
| 複数ワーカーモード | NUM_THREADS > 1 の場合は表示しない |
| 問題数が0 | 問題が発見されていない場合は進捗メッセージのみ（本通知は表示しない） |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[診断ファイル処理開始] --> B{QUIETモード?}
    B -->|Yes| D[表示スキップ]
    B -->|No| C{0.2秒経過?}
    C -->|No| D
    C -->|Yes| E[resultsから問題数集計]
    E --> F{問題数 > 0?}
    F -->|No| G[プログレスバーのみ表示]
    F -->|Yes| H[CLI_CHECK_PROGRESSメッセージ追加]
    H --> I[コンソール出力]
    G --> I
    I --> J[次のファイル処理へ]
    D --> J
```

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

### 参照テーブル一覧

本機能はデータベースを使用しない。全てインメモリで処理される。

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| results (Lua table) | 診断結果の蓄積 | uri => diagnostics[] の形式 |

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

#### results テーブル

| 参照項目（カラム名） | 用途 | 取得条件 |
|-------------------|------|---------|
| pairs(results) | ファイル数と問題数の集計 | 全エントリを走査 |

### 更新テーブル一覧

なし（読み取り専用）

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 出力失敗 | コンソール出力が不可能な場合 | 処理は継続（通知のみスキップ） |

### リトライ仕様

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

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 更新間隔 | 最小0.2秒 |
| 1日あたり上限 | なし |

### 配信時間帯

制限なし（CLI実行時のみ）

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

- 機密情報は含まれない（問題数とファイル数のみ）
- ファイルパスは直接表示されない

## 備考

- プログレスバーは `>>>>>>====` 形式で表示され、進捗率を視覚的に示す
- 行頭に `\x0D`（キャリッジリターン）を出力して同じ行を上書きすることで、リアルタイム更新を実現している

---

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

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

### 推奨読解順序

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

まず、診断結果がどのようなデータ構造で管理されているかを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | check_worker.lua | `script/cli/check_worker.lua` | results テーブルの構造（uri => diagnostics[]）を確認 |

**読解のコツ**: `results` 変数は207行目で空テーブルとして初期化され、publishDiagnostics コールバックで更新される。

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

処理の起点となる関数を特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | check_worker.lua | `script/cli/check_worker.lua` | `export.runCLI()` 関数がエントリーポイント |

**主要処理フロー**:
1. **178行目**: `export.runCLI()` 関数定義開始
2. **206行目**: `lastClock = os.clock()` で時間計測開始
3. **207行目**: `results = {}` で結果テーブル初期化
4. **249-261行目**: ファイルごとの診断ループ

#### Step 3: 進捗表示ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | check_worker.lua | `script/cli/check_worker.lua` | `report_progress()` 関数（119-144行目） |

**主要処理フロー**:
- **122-128行目**: resultsから問題数を集計
- **130-139行目**: プログレスバーを構築
- **140-142行目**: 問題数が0より大きい場合、CLI_CHECK_PROGRESSメッセージを追加

#### Step 4: ローカライゼーションを理解する

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

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

```
export.runCLI() [check_worker.lua:178]
    │
    ├─ lclient.start() [check_worker.lua:215]
    │      │
    │      ├─ diag.doDiagnostic() [check_worker.lua:252]
    │      │      └─ publishDiagnostics callback [check_worker.lua:223-229]
    │      │             └─ results[uri] = diagnostics
    │      │
    │      └─ report_progress() [check_worker.lua:258]
    │             └─ lang.script('CLI_CHECK_PROGRESS', ...) [check_worker.lua:141]
    │
    └─ lang.script('CLI_CHECK_SUCCESS/RESULTS', ...) [check_worker.lua:284-289]
```

### データフロー図

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

ファイルURI ───────▶ diag.doDiagnostic() ───────▶ results テーブル
                                                       │
                                                       ▼
                        report_progress() ◀─────── 問題数集計
                              │
                              ▼
                    lang.script('CLI_CHECK_PROGRESS') ───▶ コンソール出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| check_worker.lua | `script/cli/check_worker.lua` | ソース | メイン処理、進捗表示ロジック |
| check.lua | `script/cli/check.lua` | ソース | マルチワーカー起動、結果集約 |
| script.lua | `locale/en-us/script.lua` | ローカライズ | 英語メッセージ定義 |
| script.lua | `locale/ja-jp/script.lua` | ローカライズ | 日本語メッセージ定義 |
| language.lua | `script/language.lua` | ソース | 多言語対応モジュール |
