# 通知設計書 84-CLI_CHECK_RESULTS_PRETTY

## 概要

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

### 本通知の処理概要

CLI_CHECK_RESULTS_PRETTYは、コマンドライン診断（--checkオプション）が完了した際に、結果ファイルの出力が指定されていない場合に表示される最終結果メッセージである。

**業務上の目的・背景**：診断結果をファイルに出力せず、コンソール上で直接結果を確認したいユースケースに対応する。開発者が素早く診断結果を確認したい場合や、CI/CDパイプラインでログ出力のみを必要とする場合に使用される。

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

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

**通知内容の概要**：「診断が完了しました。{問題数} 個の問題が発見されました」という形式で、診断の完了と発見された問題の総数を示す。ファイルパスは表示されない。

**期待されるアクション**：ユーザーはコンソール上に直前に出力された詳細な診断結果（pretty format）を確認し、検出された問題を修正する。

## 通知種別

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

## 送信仕様

### 基本情報

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

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

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

## 通知テンプレート

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

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

### 本文テンプレート

```
日本語:
診断が完了しました。{count} 個の問題が発見されました

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

### 添付ファイル

なし（本通知は結果ファイルを出力しない場合に使用）

## テンプレート変数

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

## 送信トリガー・条件

### トリガー一覧

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

### 送信抑止条件

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

## 処理フロー

### 送信フロー

```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) | 総問題数の集計 | 全エントリを走査 |

### 更新テーブル一覧

なし（本通知はファイル出力を伴わない）

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 出力失敗 | コンソール出力が不可能な場合 | 処理は継続 |

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

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

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

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

## 備考

- 本通知の前に、各診断結果がpretty形式（色付き、ソースコード行付き）でコンソールに出力されている
- CHECK_FORMAT=pretty または CHECK_FORMAT未指定の場合にpretty形式出力が有効
- マルチワーカーモードでも、outpathがない場合は本通知が使用される

---

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

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

### 推奨読解順序

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

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

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

**読解のコツ**: pretty形式の出力は`report_pretty()`関数（73-112行目）で行われている。

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

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

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

**主要処理フロー**:
1. **267-273行目**: 問題数の集計
2. **275-281行目**: JSON出力条件チェック（outpathがnil以外の場合）
3. **289行目**: CLI_CHECK_RESULTS_PRETTY表示条件

#### Step 3: pretty形式出力を理解する

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

**主要処理フロー**:
- **83-101行目**: 各診断結果を色付きで出力
- **103-110行目**: ソースコード行とキャレット表示

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

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

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

```
export.runCLI() [check_worker.lua:178]
    │
    ├─ lclient.start() [check_worker.lua:215]
    │      │
    │      └─ publishDiagnostics callback [check_worker.lua:223-229]
    │             └─ report_pretty() [check_worker.lua:227]
    │                    └─ 各診断結果を色付きで出力
    │
    ├─ 結果集計 [check_worker.lua:267-273]
    │
    └─ 結果表示分岐 [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)
```

### データフロー図

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

診断結果 ─────────▶ report_pretty() ───────▶ 色付きコンソール出力
                          │                        │
                          ▼                        ▼
                     結果集計 ───────▶ count（問題数）
                          │
                          ▼
               lang.script('CLI_CHECK_RESULTS_PRETTY') ───▶ サマリー出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| check_worker.lua | `script/cli/check_worker.lua` | ソース | 診断処理、pretty形式出力、結果表示 |
| check.lua | `script/cli/check.lua` | ソース | マルチワーカー時の結果表示 |
| script.lua | `locale/en-us/script.lua` | ローカライズ | 英語メッセージ定義 |
| script.lua | `locale/ja-jp/script.lua` | ローカライズ | 日本語メッセージ定義 |
