# 機能設計書 74-コマンドラインチェック

## 概要

本ドキュメントは、Lua Language ServerにおけるCLIモードでの診断チェック機能の設計を記述する。この機能は、コマンドラインからLuaプロジェクトの静的解析を実行し、診断結果をファイルまたは標準出力に出力する。CI/CDパイプラインでの品質チェックに活用できる。

### 本機能の処理概要

**業務上の目的・背景**：開発チームは継続的インテグレーション（CI）パイプラインでコード品質をチェックしたい場合がある。エディタを起動せずにコマンドラインから診断を実行できれば、自動化されたビルドプロセスに組み込むことができる。本機能はこのニーズに応え、Luaプロジェクト全体の診断レポートを生成する。

**機能の利用シーン**：
- CI/CDパイプラインでのコード品質チェック
- プルリクエスト時の自動診断
- バッチ処理での複数プロジェクトチェック
- コマンドラインからの手動診断実行

**主要な処理内容**：
1. コマンドライン引数の解析と検証
2. マルチスレッドでの並列診断実行
3. 診断結果の収集とマージ
4. JSON形式またはpretty形式での結果出力
5. 終了コードによる成否判定

**関連システム・外部連携**：
- 診断システム（構文診断、各種診断ルール）
- ワークスペース管理システム
- ファイルシステム（結果出力）

**権限による制御**：特になし。コマンドライン実行可能なユーザーが利用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 38 | 診断チェック | 主画面 | プロジェクトの診断レポートを生成するCLI処理 |
| 39 | 診断ワーカー | 主画面 | 診断チェックの並列ワーカープロセス |

## 機能種別

診断処理 / バッチ処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| --check | string | Yes | チェック対象のワークスペースパス | 有効なディレクトリパス |
| --checklevel | string | No | 最小診断レベル（Error/Warning/Information/Hint） | 指定値のいずれか |
| --check_format | string | No | 出力形式（json/pretty） | json または pretty |
| --check_out_path | string | No | 結果出力ファイルパス | 書き込み可能なパス |
| --num_threads | number | No | 並列スレッド数 | 正の整数 |
| --quiet | boolean | No | 進捗出力を抑制 | - |

### 入力データソース

- コマンドライン引数
- ワークスペースのLuaファイル

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| diagnostics | table | ファイルごとの診断結果 |
| exitCode | number | 0: 問題なし, 1: 問題あり |

### 出力先

- 標準出力（pretty形式）
- JSONファイル（json形式）
- 終了コード

## 処理フロー

### 処理シーケンス

```
1. コマンドライン引数解析
   └─ --check, --checklevel等を解析
2. ワーカープロセス起動
   └─ num_threads分のサブプロセスを起動
3. 各ワーカーで診断実行
   └─ ファイルを分担して診断
4. 結果収集
   └─ 各ワーカーの部分結果を収集
5. 結果マージ
   └─ 全結果を統合
6. 結果出力
   └─ JSON/pretty形式で出力
7. 終了コード返却
```

### フローチャート

```mermaid
flowchart TD
    A[CLI起動: --check] --> B[引数解析]
    B --> C{マルチスレッド?}
    C -->|Yes| D[ワーカープロセス起動]
    C -->|No| E[単一プロセスで診断]
    D --> F[各ワーカーで診断実行]
    F --> G[結果ファイル出力]
    G --> H[結果マージ]
    E --> I[診断実行]
    I --> J[結果出力]
    H --> J
    J --> K{問題あり?}
    K -->|Yes| L[exit code 1]
    K -->|No| M[exit code 0]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-74-01 | デフォルトレベル | checklevelのデフォルトはWarning | 未指定時 |
| BR-74-02 | デフォルト形式 | check_formatのデフォルトはpretty | 未指定時 |
| BR-74-03 | マルチスレッド進捗 | num_threads > 1の場合、進捗出力は抑制 | マルチスレッド時 |
| BR-74-04 | 終了コード | 問題が1件以上あればexit code 1 | 常時 |

### 計算ロジック

**引数変換ロジック**:
```lua
-- --check を --check_worker に変換
if arg:lower():match('^%-%-check$') then
    args[#args + 1] = '--check_worker'
end
-- スレッドIDを追加
args[#args + 1] = '--thread_id'
args[#args + 1] = tostring(threadId)
```

## データベース操作仕様

### 操作別データベース影響一覧

本機能はデータベース操作を行わない。ファイルシステムへの出力のみ。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| CLI_CHECK_ERROR_TYPE | 引数型エラー | --checkが文字列でない | エラーメッセージ出力 |
| CLI_CHECK_ERROR_URI | URIエラー | 無効なパス指定 | エラーメッセージ出力 |
| CLI_CHECK_ERROR_LEVEL | レベルエラー | 無効なchecklevel | エラーメッセージ出力 |

### リトライ仕様

リトライは行わない。エラー時は即座に終了。

## トランザクション仕様

トランザクション管理は不要。読み取りと出力のみの処理。

## パフォーマンス要件

- マルチスレッドによる並列処理で大規模プロジェクトの診断を高速化
- 各ワーカーは独立してファイルを処理
- 結果はJSONファイル経由でマージ

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

- 指定されたディレクトリ外へのアクセスは制限
- 出力ファイルパスの検証

## 備考

- --check_workerは内部用オプションで、ワーカープロセス用
- 進捗表示はマルチスレッド時に自動的に抑制される

---

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

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

### 推奨読解順序

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

コマンドライン引数の構造を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | help.lua | `script/cli/help.lua` | 10-147行目: 全CLIオプションの定義 |

**読解のコツ**: `args`テーブルに各オプションのtype, description, default, exampleが定義されている。

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

CLIチェックのメイン処理。

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

**主要処理フロー**:
1. **51行目**: NUM_THREADSからスレッド数取得
2. **53-63行目**: 実行ファイルパスの解決
3. **69-78行目**: ワーカープロセスの起動
4. **80-83行目**: 全ワーカーの完了待ち
5. **85-116行目**: 結果のマージと出力

#### Step 3: 引数変換を理解する

ワーカープロセス用の引数変換。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | check.lua | `script/cli/check.lua` | 14-48行目: buildArgs関数 |

**主要処理フロー**:
- **20-21行目**: --checkを--check_workerに変換
- **35-36行目**: --thread_idを追加
- **44-45行目**: 部分結果の出力先を設定

#### Step 4: 結果マージを理解する

複数ワーカーの結果統合。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | check.lua | `script/cli/check.lua` | 85-116行目: 結果マージ処理 |

**主要処理フロー**:
- **88-98行目**: 各ワーカーのJSONファイル読み込みとマージ
- **102-104行目**: 最終結果のJSON出力

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

```
export.runCLI (公開API)
    │
    ├─ buildArgs(minIndex, numThreads, threadId, format, quiet)
    │      └─ ワーカー用引数を構築
    │
    ├─ subprocess.spawn({args})
    │      └─ ワーカープロセス起動
    │
    ├─ process:wait()
    │      └─ 各ワーカーの完了待ち
    │
    └─ 結果マージ処理
           │
           ├─ json.decode(util.loadFile(logFile))
           │      └─ 部分結果読み込み
           │
           └─ util.saveFile(outpath, jsonb.beautify(mergedResults))
                  └─ 最終結果出力
```

### データフロー図

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

コマンドライン引数 ────▶ runCLI() ─────────────▶ ┐
  --check=path              │                      │
  --checklevel=Warning      │                      │
  --check_format=json       │                      │
                            ▼                      │
                     buildArgs()                   │
                            │                      │
                            ▼                      │
                     ワーカー起動                  │
                     (subprocess)                  ├─▶ 診断結果
                            │                      │   (JSON/pretty)
                            ▼                      │
                     各ワーカー診断                │
                            │                      │
                            ▼                      │
                     部分結果出力                  │
                     (check-partial-N.json)        │
                            │                      │
                            ▼                      │
                     結果マージ ───────────────▶ ┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| check.lua | `script/cli/check.lua` | ソース | CLIチェックのメインモジュール |
| help.lua | `script/cli/help.lua` | ソース | CLIヘルプ・オプション定義 |
| json.lua | `script/json.lua` | ソース | JSON解析 |
| json-beautify.lua | `script/json-beautify.lua` | ソース | JSON整形出力 |
| utility.lua | `script/utility.lua` | ソース | ファイル操作ユーティリティ |
| language.lua | `script/language.lua` | ソース | 多言語メッセージ |
