# 画面設計書 38-診断チェック

## 概要

本ドキュメントは、Lua Language ServerのCLIコマンド「診断チェック（--check）」の画面設計書です。

### 本画面の処理概要

この画面（CLIコマンド）は、指定されたワークスペースに対して診断を実行し、エラーや警告をレポートする機能を提供します。

**業務上の目的・背景**：
Luaプロジェクトの品質を維持するために、コードの静的解析を実行してエラーや警告を検出することは重要です。本コマンドは、CI/CDパイプラインや開発者のローカル環境で、Language Serverの診断機能をバッチ実行できるようにします。複数のワーカープロセスを使用した並列処理により、大規模プロジェクトでも効率的に診断を実行できます。結果はJSON形式またはPretty形式で出力でき、他のツールとの連携やヒューマンリーダブルな確認が可能です。

**画面へのアクセス方法**：
本コマンドは、以下の方法でトリガーされます：
- コマンドラインで `lua-language-server --check=<workspace_path>` を実行

**主要な操作・処理内容**：
1. ワーカープロセス数を決定
2. 各ワーカープロセスを起動（--check_worker）
3. 各ワーカーの完了を待機
4. 複数ワーカーの場合、結果をマージ
5. 結果をJSON/Pretty形式で出力
6. 診断結果に応じた終了コードを返す

**画面遷移**：
- 入力元：コマンドライン起動
- 出力先：標準出力（stdout）および/またはJSONファイル

**権限による表示制御**：
特別な権限制御はありません。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 74 | コマンドラインチェック | 主機能 | プロジェクトの診断レポートを生成するCLI処理 |
| 30 | 構文診断 | 補助機能 | 構文エラーの検出 |
| 31 | 未定義グローバル (undefined-global) | 補助機能 | 未定義グローバル変数の検出 |
| 32 | 未使用ローカル (unused-local) | 補助機能 | 未使用ローカル変数の検出 |

## 画面種別

CLI（コマンドライン出力）

## URL/ルーティング

- CLIオプション: `--check=<workspace_path>`
- ハンドラファイル: `script/cli/check.lua`
- 関連オプション:
  - `--checklevel`: 診断レベルの最小値（Error, Warning, Information, Hint）
  - `--check_format`: 出力形式（json, pretty）
  - `--check_out_path`: JSON出力ファイルパス

## 入出力項目

### 入力パラメータ

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| --check | string | Yes | チェック対象ワークスペースのパス |
| --checklevel | string | No | 診断レベルの最小値（デフォルト: Warning） |
| --check_format | string | No | 出力形式 json/pretty（デフォルト: pretty） |
| --check_out_path | string | No | JSON出力ファイルパス |
| --num_threads | number | No | ワーカースレッド数 |
| --quiet | flag | No | 進捗表示を抑制 |

### 出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| stdout | text | Pretty形式の診断結果（--check_format=pretty時） |
| file | JSON | JSON形式の診断結果（--check_format=json時） |
| exit code | number | 0: 診断パス、1: 診断エラーあり |

## 表示項目

### Pretty形式出力

| 項目名 | 表示内容 |
|--------|---------|
| ファイルパス | 相対パス:行番号:列番号 |
| 重大度 | [Error], [Warning], [Information], [Hint] |
| メッセージ | 診断メッセージ |
| コード | (diagnostic_code) |
| 該当行 | ソースコードの該当行 |
| キャレット | 問題箇所を示す^記号 |

### 進捗表示

| 項目名 | 表示内容 |
|--------|---------|
| プログレスバー | `>>>>>>>>>>>========= ` |
| 進捗数 | `0123/0456` |
| エラーサマリー | `[X errors in Y files]` |

## イベント仕様

### 1-診断チェック実行（メインプロセス）

1. **スレッド数決定**: NUM_THREADSまたは1
2. **実行ファイル特定**: arg配列から実行ファイルパスを取得
3. **進捗表示**: マルチスレッド時にワーカー数を表示
4. **ワーカー起動**: 各ワーカープロセスを起動
5. **完了待機**: 全ワーカーの完了を待機
6. **結果マージ**: 複数ワーカーの結果をマージ
7. **結果出力**: JSON/Pretty形式で出力
8. **終了コード返却**: 診断結果に応じて0または1を返す

### 2-診断チェック実行（ワーカープロセス）

1. **パラメータ検証**: CHECK_WORKERのパス検証
2. **checklevel検証**: 有効な診断レベルか確認
3. **LSPクライアント起動**: lclientを初期化
4. **ワークスペース準備**: ws.awaitReady()で待機
5. **診断レベル適用**: apply_check_level()で診断を設定
6. **ファイル診断**: 各ファイルに対してdiag.doDiagnostic()を実行
7. **進捗表示**: 定期的に進捗を更新
8. **結果出力**: JSON/Pretty形式で出力

## データベース更新仕様

本機能はデータの更新を行いません。

## メッセージ仕様

| メッセージID | 種別 | 表示条件 | メッセージ内容 |
|-------------|------|---------|--------------|
| CLI_CHECK_MULTIPLE_WORKERS | Info | マルチスレッド時 | ワーカー数を表示 |
| CLI_CHECK_INITING | Info | 初期化中 | 初期化中メッセージ |
| CLI_CHECK_SUCCESS | Info | 診断成功（エラーなし） | 成功メッセージ |
| CLI_CHECK_RESULTS_OUTPATH | Info | JSON出力時 | 結果ファイルパス |
| CLI_CHECK_RESULTS_PRETTY | Info | Pretty出力時 | 結果サマリー |
| CLI_CHECK_ERROR_TYPE | Error | パラメータ型エラー | 型エラーメッセージ |
| CLI_CHECK_ERROR_URI | Error | URI解決失敗 | URIエラーメッセージ |
| CLI_CHECK_ERROR_LEVEL | Error | 不正なchecklevel | レベルエラーメッセージ |
| CLI_CHECK_PROGRESS | Info | 進捗表示 | エラー数とファイル数 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| ワークスペースパス未指定 | エラーメッセージを表示して終了 |
| 不正な診断レベル | エラーメッセージを表示して終了 |
| ワーカープロセス失敗 | エラーを出力 |
| URI解決失敗 | エラーメッセージを表示して終了 |

## 備考

- マルチスレッド実行時は、ファイルリストをソートしてワーカーに分散します
- 各ワーカーは `i % numThreads + 1 == threadId` の条件でファイルを処理します
- 診断結果はDiagnosticSeverityでフィルタリングされます
- ANSI カラーコードを使用して出力を色分けします（NO_COLOR環境変数で無効化可能）
- 終了コードはCI/CD統合で使用できます

---

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

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

### 推奨読解順序

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

まず、診断結果で使用されるデータ構造を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | define.lua | `script/proto/define.lua` | DiagnosticSeverityの定義を理解 |

**読解のコツ**: `DiagnosticSeverity`はError=1, Warning=2, Information=3, Hint=4の列挙型です。

#### Step 2: エントリーポイントを理解する（メインプロセス）

メインプロセスの起点を確認します。

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

**主要処理フロー**:
1. **51行目**: スレッド数を取得
2. **53-63行目**: 実行ファイルパスを特定
3. **69-78行目**: ワーカープロセスを起動
4. **80-83行目**: ワーカー完了を待機
5. **85-115行目**: 結果をマージして出力

#### Step 3: ワーカープロセスを理解する

ワーカープロセスの処理を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | check_worker.lua | `script/cli/check_worker.lua` | runCLI関数（178-293行目） |

**主要処理フロー**:
- **185-195行目**: パラメータ検証
- **215-229行目**: LSPクライアント初期化と診断結果ハンドラ登録
- **240-244行目**: 診断レベル適用
- **246-261行目**: ファイルを順次診断
- **267-291行目**: 結果出力

#### Step 4: Pretty形式出力を理解する

Pretty形式の出力処理を確認します。

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

**主要処理フロー**:
- **74行目**: 相対パスを計算
- **83-102行目**: 各診断結果を色付きで出力
- **103-110行目**: ソースコードと該当箇所を表示

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

```
lua-language-server --check=<path>
    │
    └─ check.lua:runCLI() (メインプロセス)
           │
           ├─ subprocess.spawn() [n個のワーカー]
           │      │
           │      └─ check_worker.lua:runCLI()
           │             │
           │             ├─ lclient:start()
           │             │
           │             ├─ client:initialize()
           │             │
           │             ├─ provider.updateConfig()
           │             │
           │             ├─ ws.awaitReady()
           │             │
           │             ├─ apply_check_level()
           │             │
           │             ├─ downgrade_checks_to_opened()
           │             │
           │             └─ [for each file]
           │                    │
           │                    ├─ files.open()
           │                    │
           │                    └─ diag.doDiagnostic()
           │
           ├─ process:wait() [全ワーカー]
           │
           └─ マージ & 出力
```

### データフロー図

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

--check=<path> ───▶ check.lua ───▶ stdout/file
                        │
                        ▼
                 スレッド数決定
                        │
                   ┌────┴────┐
                   ▼         ▼
              Worker 1   Worker N
                   │         │
                   ▼         ▼
              診断実行   診断実行
                   │         │
                   ▼         ▼
              結果JSON   結果JSON
                   │         │
                   └────┬────┘
                        ▼
                   結果マージ
                        │
                   ┌────┴────┐
                   ▼         ▼
              Pretty形式   JSON形式
              (stdout)    (file)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| check.lua | `script/cli/check.lua` | ソース | メインプロセス（ワーカー管理） |
| check_worker.lua | `script/cli/check_worker.lua` | ソース | ワーカープロセス（診断実行） |
| lclient.lua | `script/lclient.lua` | ソース | LSPクライアントエミュレータ |
| diagnostic.lua | `script/provider/diagnostic.lua` | ソース | 診断処理 |
| define.lua | `script/proto/define.lua` | ソース | 診断重大度定義 |
| json-beautify.lua | `script/json-beautify.lua` | ソース | JSON整形 |
| language.lua | `script/language.lua` | ソース | 多言語メッセージ |
