# 通知設計書 82-CLI_CHECK_RESULTS

## 概要

本ドキュメントは、Lua Language Serverのコマンドライン診断機能における「診断結果（問題あり）」通知（CLI_CHECK_RESULTS）の設計を記載する。

### 本通知の処理概要

CLI_CHECK_RESULTSは、コマンドライン診断（--checkオプション）が完了した際に、問題が発見された場合に表示される最終結果メッセージである。

**業務上の目的・背景**：コマンドラインでの診断処理が完了した際、ユーザーはその結果を把握する必要がある。本通知は診断が完了し、何件の問題が発見されたか、また詳細な結果がどこで確認できるかを明確に伝える役割を果たす。これにより、ユーザーは次のアクション（コードの修正や結果ファイルの確認）を適切に判断できる。

**通知の送信タイミング**：すべてのファイルの診断処理が完了した直後、結果が集計され、問題が1件以上発見された場合に表示される。

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

**通知内容の概要**：「診断が完了しました。{問題数} 個の問題が見つかりました。{ファイルパス} を参照してください」という形式で、診断の完了と結果ファイルの場所を示す。

**期待されるアクション**：ユーザーは指定されたファイルパス（通常はJSON形式の結果ファイル）を開き、詳細な診断結果を確認する。その後、検出された問題を修正する。

## 通知種別

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

## 送信仕様

### 基本情報

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

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

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

## 通知テンプレート

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

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

### 本文テンプレート

```
日本語:
診断が完了しました。{count} 個の問題が見つかりました。{outpath} を参照してください

英語:
Diagnosis complete, {count} problems found, see {outpath}
```

### 添付ファイル

| ファイル名 | 形式 | 条件 | 説明 |
|----------|------|------|------|
| check.json | JSON | CHECK_OUT_PATH指定時 | 診断結果の詳細をJSON形式で出力 |

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| count | 発見された診断問題の総数 | results テーブルから集計 | Yes |
| outpath | 結果ファイルのパス | CHECK_OUT_PATH または LOGPATH .. '/check.json' | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| CLI実行 | 全ファイル診断完了 | count > 0 かつ outpath が設定されている場合 | 診断終了時の最終レポート |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| QUIET=true | 静音モードが有効な場合は表示しない |
| count == 0 | 問題が発見されていない場合はCLI_CHECK_SUCCESSを表示 |
| outpathがnil | 出力パスがない場合はCLI_CHECK_RESULTS_PRETTYを表示 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[全ファイル診断完了] --> B[結果集計]
    B --> C{QUIETモード?}
    C -->|Yes| D[表示スキップ]
    C -->|No| E{count == 0?}
    E -->|Yes| F[CLI_CHECK_SUCCESS表示]
    E -->|No| G{outpath設定あり?}
    G -->|Yes| H[CLI_CHECK_RESULTS表示]
    G -->|No| I[CLI_CHECK_RESULTS_PRETTY表示]
    F --> J[終了]
    H --> J
    I --> J
    D --> J
```

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

### 参照テーブル一覧

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

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

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

#### results テーブル

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

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| check.json (ファイル) | CREATE | 診断結果をJSON形式でファイル出力 |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| ファイル書き込み失敗 | 出力パスに書き込み権限がない場合 | エラーメッセージを表示 |
| 出力失敗 | コンソール出力が不可能な場合 | 処理は継続 |

### リトライ仕様

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

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1回の診断あたり | 最大1回 |
| 1日あたり上限 | なし |

### 配信時間帯

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

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

- ファイルパスが表示されるが、これはユーザーが指定したパスまたはログパス
- 診断結果ファイルにはソースコードの一部が含まれる可能性がある

## 備考

- 本通知はシングルワーカーモード、マルチワーカーモードの両方で使用される
- マルチワーカーモードでは、check.lua が各ワーカーの結果をマージした後に表示

---

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

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

### 推奨読解順序

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

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

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

**読解のコツ**: `results` 変数は207行目で空テーブルとして初期化され、267-273行目で空の結果を削除している。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | check_worker.lua | `script/cli/check_worker.lua` | `export.runCLI()` 関数の最終部分（283-291行目） |

**主要処理フロー**:
1. **267-273行目**: 問題数の集計と空結果の削除
2. **275-281行目**: 結果ファイルの出力（JSON形式）
3. **283-291行目**: 結果メッセージの表示分岐

#### Step 3: マルチワーカー時の処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | check.lua | `script/cli/check.lua` | マルチワーカー結果のマージ処理（85-116行目） |

**主要処理フロー**:
- **86-98行目**: 各ワーカーの結果ファイルを読み込みマージ
- **107-115行目**: マージ後の結果メッセージ表示

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

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

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

```
export.runCLI() [check_worker.lua:178]
    │
    ├─ 診断処理ループ [check_worker.lua:249-261]
    │
    ├─ 結果集計 [check_worker.lua:267-273]
    │
    ├─ util.saveFile() [check_worker.lua:280]
    │      └─ check.json 出力
    │
    └─ 結果表示分岐 [check_worker.lua:283-291]
           ├─ count == 0 → lang.script('CLI_CHECK_SUCCESS')
           ├─ outpath あり → lang.script('CLI_CHECK_RESULTS', count, outpath)
           └─ outpath なし → lang.script('CLI_CHECK_RESULTS_PRETTY', count)

export.runCLI() [check.lua:50] (マルチワーカーモード)
    │
    ├─ ワーカープロセス起動 [check.lua:69-78]
    │
    ├─ ワーカー完了待ち [check.lua:80-83]
    │
    ├─ 結果マージ [check.lua:86-98]
    │
    └─ 結果表示 [check.lua:107-115]
           └─ lang.script('CLI_CHECK_RESULTS_OUTPATH', count, outpath)
```

### データフロー図

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

診断結果 ─────────▶ results テーブル集計 ───────▶ count（問題数）
                                                       │
                                                       ▼
                        util.saveFile() ◀─────── JSON形式変換
                              │
                              ▼
                         check.json ───────▶ outpath
                              │
                              ▼
                    lang.script('CLI_CHECK_RESULTS') ───▶ コンソール出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| 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` | ローカライズ | 日本語メッセージ定義 |
| json-beautify.lua | `script/json-beautify.lua` | ソース | JSON整形出力 |
| utility.lua | `script/utility.lua` | ソース | ファイル保存ユーティリティ |
