# 機能設計書 2-jest-cli

## 概要

本ドキュメントは、Jestテスティングフレームワークのコマンドラインインターフェース「jest-cli」の機能設計を記述したものである。

### 本機能の処理概要

jest-cliパッケージは、ユーザーがターミナルから`jest`コマンドを実行した際の処理を担当するCLIモジュールである。コマンドライン引数の解析、設定の読み込み、そして@jest/coreへの処理の委譲を行う。

**業務上の目的・背景**：開発者がテストを実行する最も一般的な方法はCLIからの実行である。jest-cliは、シンプルなコマンドラインインターフェースを提供することで、開発者が複雑な設定なしにテストを実行できるようにする。npmスクリプト、CI/CDパイプライン、ローカル開発環境など、あらゆる環境からテストを一貫した方法で実行できることが重要である。

**機能の利用シーン**：
- ターミナルから`jest`コマンドを直接実行する場合
- `npm test`や`yarn test`でJestを実行する場合
- CI/CDパイプラインでテストを自動実行する場合
- `--watch`モードで開発中にテストを継続監視する場合

**主要な処理内容**：
1. `bin/jest.js`がエントリポイントとなり、run関数を呼び出す
2. yargsライブラリを使用してコマンドライン引数を解析
3. 引数に基づいて設定を構築
4. @jest/coreのrunCLI関数にテスト実行を委譲
5. テスト結果に応じた終了コードを返却

**関連システム・外部連携**：
- @jest/core: テスト実行の中核機能を提供
- yargs: コマンドライン引数の解析
- chalk: ターミナル出力の色付け
- jest-config: 設定ファイルの読み込みと正規化

**権限による制御**：特になし。ファイルシステムへのアクセス権限は実行ユーザーの権限に依存する。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| N/A | N/A | N/A | 本機能はCLIであり、画面は存在しない |

## 機能種別

コマンドライン処理 / テスト実行制御

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| --config | string | No | 設定ファイルパス | 存在するパスまたはJSON文字列 |
| --coverage | boolean | No | カバレッジ計測を有効化 | N/A |
| --watch | boolean | No | ファイル変更監視モード | N/A |
| --watchAll | boolean | No | 全ファイル監視モード | N/A |
| --runInBand | boolean | No | シリアル実行モード | N/A |
| --testPathPattern | string | No | テストパスのフィルタパターン | 有効な正規表現 |
| --testNamePattern | string | No | テスト名のフィルタパターン | 有効な正規表現 |
| --updateSnapshot | boolean | No | スナップショット更新モード | N/A |
| --verbose | boolean | No | 詳細出力モード | N/A |
| --maxWorkers | number/string | No | 最大ワーカー数 | 正の整数または割合 |
| --bail | boolean/number | No | 失敗時の中断設定 | N/A |
| --shard | string | No | シャーディング設定 | M/N形式 |

### 入力データソース

- process.argv: コマンドライン引数
- 設定ファイル: jest.config.js, jest.config.ts, package.jsonのjestフィールド

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| テスト結果 | stdout | テスト実行結果のサマリー |
| エラーメッセージ | stderr | エラー発生時のメッセージ |
| 終了コード | number | 0:成功, 1:テスト失敗, 2:設定エラー |

### 出力先

- 標準出力（stdout）: テスト結果、進捗情報
- 標準エラー出力（stderr）: エラーメッセージ、警告
- プロセス終了コード: テスト結果のステータス

## 処理フロー

### 処理シーケンス

```
1. bin/jest.js実行
   └─ run関数を呼び出し
2. 引数解析（yargs）
   └─ コマンドライン引数をパース
3. 設定検証
   └─ 設定値の妥当性を確認
4. @jest/core呼び出し
   └─ runCLI関数にテスト実行を委譲
5. 結果出力
   └─ テスト結果をフォーマットして出力
6. 終了コード設定
   └─ process.exitCode設定
```

### フローチャート

```mermaid
flowchart TD
    A[jest コマンド実行] --> B[bin/jest.js]
    B --> C[run 関数呼び出し]
    C --> D[yargs で引数解析]
    D --> E{引数検証}
    E -->|エラー| F[エラー出力・終了]
    E -->|OK| G[@jest/core runCLI 呼び出し]
    G --> H[テスト実行]
    H --> I{テスト結果}
    I -->|成功| J[終了コード 0]
    I -->|失敗| K[終了コード 1]
    I -->|エラー| L[終了コード 2]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 終了コード規約 | テスト成功=0, テスト失敗=1, 設定エラー=2 | 常時 |
| BR-002 | CI環境判定 | CI環境では--ciフラグが自動有効化 | CI環境検出時 |
| BR-003 | 監視モード排他 | --watchと--watchAllは排他的 | 両方指定時 |
| BR-004 | カバレッジ出力 | --coverageで詳細なカバレッジレポート出力 | 指定時 |

### 計算ロジック

maxWorkersの算出ロジック:
- 未指定の場合: `os.cpus().length - 1`（最低1）
- 割合指定の場合: `Math.ceil(cpuCount * percentage)`
- 数値指定の場合: そのまま使用

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

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

データベース操作は本パッケージでは行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| EXIT_2 | 設定エラー | 無効な設定オプション指定 | エラーメッセージを確認し、設定を修正 |
| EXIT_1 | テスト失敗 | テストケースの失敗 | 失敗したテストを修正 |
| ENOENT | ファイル不存在 | 設定ファイルが見つからない | パスを確認 |

### リトライ仕様

CLI自体にリトライ機能はない。テスト実行時のリトライはjest-circusが担当。

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

トランザクション処理は本パッケージには存在しない

## パフォーマンス要件

- CLI起動時間: 可能な限り短く（遅延ロードの活用）
- メモリ使用量: テスト実行はワーカープロセスで分離されるため、親プロセスのメモリ使用は最小限

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

- コマンドライン引数は信頼されるユーザー入力として扱われる
- 設定ファイルはJavaScriptとして評価されるため、信頼できるファイルのみを使用すべき

## 備考

- bin/jest.jsは#!/usr/bin/env nodeで始まる実行可能スクリプト
- --helpオプションで利用可能なすべてのオプションを表示可能

---

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

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

### 推奨読解順序

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

CLIで使用される引数の型定義を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | args.ts | `packages/jest-cli/src/args.ts` | CLIオプションの定義と型 |

**読解のコツ**: yargsのオプション定義形式に従っており、各オプションのtype、alias、description、default値が定義されている。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | jest.js | `packages/jest-cli/bin/jest.js` | 実行可能スクリプトのエントリポイント |
| 2-2 | index.ts | `packages/jest-cli/src/index.ts` | モジュールのエクスポート |

**主要処理フロー**:
1. **jest.js**: run関数をインポートして即座に呼び出し
2. **index.ts 8-9行目**: run関数とyargsの型をエクスポート

#### Step 3: run関数の実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | run.ts | `packages/jest-cli/src/run.ts` | CLI実行のメインロジック |

**主要処理フロー**:
- **17-25行目**: buildArgv関数でyargsを使用して引数を解析
- **27-45行目**: run関数の実装、@jest/coreのrunCLIを呼び出し
- **47-55行目**: テスト結果に応じた終了コードの設定

#### Step 4: 引数定義の詳細を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | args.ts | `packages/jest-cli/src/args.ts` | 全てのCLIオプション定義 |

**主要処理フロー**:
- **各オプション定義**: alias、default、description、type、requiresArgが定義
- **usage文字列**: ヘルプメッセージのテンプレート

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

```
bin/jest.js
    │
    └─ src/run.ts
           │
           ├─ src/args.ts (引数定義)
           │
           ├─ yargs (引数解析)
           │
           └─ @jest/core/runCLI
                  │
                  ├─ jest-config (設定読み込み)
                  │
                  └─ runJest (テスト実行)
```

### データフロー図

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

process.argv ───────▶ yargs.parse ───────▶ 引数オブジェクト
                            │
                            ▼
jest.config.* ───────▶ readConfig ───────▶ 設定オブジェクト
                            │
                            ▼
                      @jest/core.runCLI
                            │
                            ├───────▶ stdout (テスト結果)
                            ├───────▶ stderr (エラー)
                            └───────▶ process.exitCode
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| jest.js | `packages/jest-cli/bin/jest.js` | 実行可能 | CLIエントリポイント |
| index.ts | `packages/jest-cli/src/index.ts` | ソース | モジュールエクスポート |
| run.ts | `packages/jest-cli/src/run.ts` | ソース | CLI実行ロジック |
| args.ts | `packages/jest-cli/src/args.ts` | ソース | CLIオプション定義 |
| package.json | `packages/jest-cli/package.json` | 設定 | パッケージ定義 |
