# 通知設計書 83-CLI_CHECK_RESULTS_OUTPATH

## 概要

本ドキュメントは、Lua Language Serverのコマンドライン診断機能における「診断結果（出力パス付き）」通知（CLI_CHECK_RESULTS_OUTPATH）の設計を記載する。

### 本通知の処理概要

CLI_CHECK_RESULTS_OUTPATHは、コマンドライン診断（--checkオプション）が完了した際に、マルチワーカーモードで実行された場合に表示される最終結果メッセージである。

**業務上の目的・背景**：マルチワーカーモードでは複数のプロセスが並列で診断を実行し、その結果を集約する。本通知は、集約された診断結果の総数と、統合された結果ファイルの出力先を明確に伝える。これにより、ユーザーは並列処理完了後の結果を一元的に確認できる。

**通知の送信タイミング**：マルチワーカーモードにおいて、すべてのワーカープロセスが完了し、各ワーカーの結果ファイルがマージされた後に表示される。

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

**通知内容の概要**：「診断が完了しました。{問題数} 個の問題が発見されました。詳しくは {出力パス} をご確認ください」という形式で、診断結果と確認先を示す。

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

## 通知種別

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

## 送信仕様

### 基本情報

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

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

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

## 通知テンプレート

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

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

### 本文テンプレート

```
日本語:
診断が完了しました。{count} 個の問題が発見されました。詳しくは {outpath} をご確認ください

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

### 添付ファイル

| ファイル名 | 形式 | 条件 | 説明 |
|----------|------|------|------|
| check.json | JSON | マルチワーカー実行時 | 全ワーカーの診断結果をマージしたJSONファイル |

## テンプレート変数

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

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| CLI実行 | 全ワーカー完了・結果マージ後 | count > 0 かつ outpath が設定されている場合 | マルチワーカー診断終了時 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| QUIET=true | 静音モードが有効な場合は表示しない |
| count == 0 | 問題が発見されていない場合はCLI_CHECK_SUCCESSを表示 |
| NUM_THREADS == 1 | シングルワーカーの場合はCLI_CHECK_RESULTSまたはCLI_CHECK_RESULTS_PRETTYを使用 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[全ワーカー完了] --> B[各ワーカー結果ファイル読み込み]
    B --> C[結果マージ]
    C --> D[マージ結果をJSONで保存]
    D --> E{QUIETモード?}
    E -->|Yes| F[表示スキップ]
    E -->|No| G{count == 0?}
    G -->|Yes| H[CLI_CHECK_SUCCESS表示]
    G -->|No| I{outpath設定あり?}
    I -->|Yes| J[CLI_CHECK_RESULTS_OUTPATH表示]
    I -->|No| K[CLI_CHECK_RESULTS_PRETTY表示]
    F --> L[終了]
    H --> L
    J --> L
    K --> L
```

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

### 参照テーブル一覧

本機能はデータベースを使用しない。全てファイルベースで処理される。

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| check-partial-{threadId}.json | 各ワーカーの部分結果 | LOGPATH配下に生成 |

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

#### check-partial-{threadId}.json

| 参照項目 | 用途 | 取得条件 |
|-------------------|------|---------|
| JSON全体 | ワーカー結果のマージ | util.loadFile()で読み込み |

### 更新テーブル一覧

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

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 部分結果読み込み失敗 | ワーカーの結果ファイルが存在しない場合 | 空配列として扱う |
| ファイル書き込み失敗 | 出力パスに書き込み権限がない場合 | エラーメッセージを表示 |

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

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

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

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

## 備考

- 本通知はマルチワーカーモード（NUM_THREADS > 1）専用
- 各ワーカーの結果は `LOGPATH/check-partial-{threadId}.json` に一時保存される
- マージ後の結果は `CHECK_OUT_PATH` または `LOGPATH/check.json` に保存される

---

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

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

### 推奨読解順序

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

まず、マルチワーカーでの結果マージの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | check.lua | `script/cli/check.lua` | mergedResults テーブルの構造を確認（86-98行目） |

**読解のコツ**: 各ワーカーの結果ファイルはJSON形式で、キーがURI、値が診断結果配列となっている。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | check.lua | `script/cli/check.lua` | `export.runCLI()` 関数（50-118行目） |

**主要処理フロー**:
1. **65-67行目**: マルチワーカー開始メッセージ表示
2. **69-78行目**: ワーカープロセスの起動
3. **80-83行目**: 全ワーカーの完了待ち
4. **85-116行目**: 結果マージと最終メッセージ表示

#### Step 3: 結果マージロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | check.lua | `script/cli/check.lua` | マージ処理（86-98行目） |

**主要処理フロー**:
- **86行目**: `mergedResults = {}` で空テーブル初期化
- **88-98行目**: 各ワーカーの結果を順次マージ

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

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

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

```
export.runCLI() [check.lua:50]
    │
    ├─ subprocess.spawn() [check.lua:71]
    │      └─ ワーカープロセス起動（check_worker.lua実行）
    │
    ├─ process:wait() [check.lua:82]
    │      └─ 全ワーカー完了待ち
    │
    ├─ util.loadFile() [check.lua:89]
    │      └─ check-partial-{threadId}.json 読み込み
    │
    ├─ json.decode() [check.lua:89]
    │      └─ JSON パース
    │
    ├─ util.saveFile() [check.lua:104]
    │      └─ check.json 出力
    │
    └─ 結果表示 [check.lua:107-115]
           ├─ count == 0 → lang.script('CLI_CHECK_SUCCESS')
           └─ count > 0 → lang.script('CLI_CHECK_RESULTS_OUTPATH', count, outpath)
```

### データフロー図

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

check-partial-1.json ──┐
check-partial-2.json ──┼──▶ json.decode() ──▶ mergedResults ──▶ check.json
check-partial-N.json ──┘         │
                                 ▼
                           count集計
                                 │
                                 ▼
                    lang.script('CLI_CHECK_RESULTS_OUTPATH') ───▶ コンソール
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| check.lua | `script/cli/check.lua` | ソース | マルチワーカー起動、結果マージ |
| check_worker.lua | `script/cli/check_worker.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` | ソース | ファイル読み書きユーティリティ |
