# 機能設計書 51-@jest/types

## 概要

本ドキュメントは、Jestテスティングフレームワークにおける `@jest/types` パッケージの機能設計について記述する。このパッケージは、Jest全体で使用されるTypeScript型定義を集約して提供するコアパッケージである。

### 本機能の処理概要

`@jest/types` は、Jestフレームワーク全体で使用される型定義を一元管理し、TypeScriptユーザーに対して型安全なテスト開発環境を提供する。

**業務上の目的・背景**：Jestは多数のパッケージで構成されるモノレポ構造であり、各パッケージ間で一貫した型定義を共有する必要がある。このパッケージにより、設定オブジェクト、テストグローバル関数、テスト結果など、Jest全体で使用される型を統一的に管理できる。また、循環依存を避けるため、型定義のみを含む軽量なパッケージとして設計されている。

**機能の利用シーン**：
- Jestの設定ファイル（jest.config.ts）をTypeScriptで記述する際の型サポート
- カスタムテストランナーやレポーターを開発する際の型定義参照
- Jest内部パッケージ間での型共有
- サードパーティのJestプラグイン開発における型定義参照

**主要な処理内容**：
1. Config型の定義：Jest設定に関する型（GlobalConfig、ProjectConfig、InitialOptions、Argv等）
2. Global型の定義：テストグローバル関数の型（describe、it、test、expect等のインターフェース）
3. Circus型の定義：jest-circusテストランナー用の状態管理型（State、DescribeBlock、TestEntry等）
4. TestResult型の定義：テスト結果データの型（AssertionResult、SerializableError等）
5. TransformTypes型の定義：コード変換結果の型（TransformResult）

**関連システム・外部連携**：
- `@jest/schemas`：Zodスキーマ定義との連携（InitialOptionsの再エクスポート）
- `istanbul-lib-coverage`：カバレッジデータ型の参照
- `istanbul-reports`：レポートオプション型の参照
- `yargs`：CLIオプション型の参照
- `chalk`：カラー出力型の参照

**権限による制御**：本パッケージは型定義のみを提供するため、実行時の権限制御は存在しない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 本パッケージは画面に直接関連しない型定義パッケージ |

## 機能種別

型定義提供 / インターフェース定義

## 入力仕様

### 入力パラメータ

本パッケージは型定義のみを提供するため、実行時の入力パラメータは存在しない。

### 入力データソース

- TypeScriptコンパイラによる型情報の読み込み
- package.jsonの`types`フィールドによるエントリポイント指定（`./build/index.d.ts`）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Circus | namespace | jest-circusテストランナー用の型定義群 |
| Config | namespace | Jest設定関連の型定義群 |
| Global | namespace | テストグローバル関数の型定義群 |
| TestResult | namespace | テスト結果データの型定義群 |
| TransformTypes | namespace | コード変換結果の型定義群 |

### 出力先

TypeScriptコンパイル時の型チェック、IDEの型補完機能、ドキュメント生成等

## 処理フロー

### 処理シーケンス

```
1. TypeScriptプロジェクトが@jest/typesをインポート
   └─ import type { Config } from '@jest/types'
2. TypeScriptコンパイラが型定義を解決
   └─ packages/jest-types/build/index.d.ts を読み込み
3. 型チェックおよび補完機能が有効化
   └─ 設定オブジェクト、テスト関数等の型サポート提供
```

### フローチャート

```mermaid
flowchart TD
    A[TypeScriptプロジェクト] --> B{@jest/typesをインポート}
    B --> C[index.tsから型をエクスポート]
    C --> D[Config型]
    C --> E[Global型]
    C --> F[Circus型]
    C --> G[TestResult型]
    C --> H[TransformTypes型]
    D --> I[TypeScript型チェック]
    E --> I
    F --> I
    G --> I
    H --> I
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-51-01 | 型の再エクスポート | index.tsは各モジュールから型のみをエクスポートする | 常時 |
| BR-51-02 | 循環依存回避 | 型定義のみを含み、実行時コードを含まない | 常時 |
| BR-51-03 | バージョン整合性 | Jest全体と同一バージョンで管理される | リリース時 |

### 計算ロジック

本パッケージは型定義のみのため、計算ロジックは存在しない。

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

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

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

該当なし

### テーブル別操作詳細

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| TS2307 | TypeScriptエラー | パッケージが見つからない | @jest/typesをインストール |
| TS2339 | TypeScriptエラー | 存在しない型プロパティへのアクセス | 型定義を確認しプロパティ名を修正 |

### リトライ仕様

該当なし（コンパイル時のみ使用）

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

該当なし

## パフォーマンス要件

- 型定義ファイルはビルド済みの`.d.ts`ファイルとして提供される
- TypeScriptコンパイラによる型解決は即座に完了する

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

- 型定義のみのパッケージであり、実行時のセキュリティリスクはない
- パッケージはnpmレジストリに公開され、public accessで配布される

## 備考

- Node.js ^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0 が必要
- バージョン 30.2.0 時点の情報

---

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

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

### 推奨読解順序

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

まず、パッケージのエントリポイントから全体構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `packages/jest-types/src/index.ts` | 5つの型モジュールの再エクスポート構造 |

**主要処理フロー**:
- **8-12行目**: 各型モジュールをtype importとしてインポート
- **14行目**: 5つの名前空間型をエクスポート

**読解のコツ**: `import type * as X from './X'` 形式で型のみをインポートし、ランタイムコードが含まれないことを確認する。

#### Step 2: Config型を理解する

Jest設定に関する最も重要な型定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Config.ts | `packages/jest-types/src/Config.ts` | Jest設定の全型定義 |

**主要処理フロー**:
- **16-33行目**: FakeableAPI型 - モック可能なタイマーAPI一覧
- **35-86行目**: FakeTimersConfig型 - フェイクタイマー設定
- **107-130行目**: HasteConfig型 - Hasteモジュールシステム設定
- **152-215行目**: DefaultOptions型 - デフォルト設定値の型
- **257-327行目**: GlobalConfig型 - グローバル設定
- **329-394行目**: ProjectConfig型 - プロジェクト単位設定
- **401-496行目**: Argv型 - CLIオプション

**読解のコツ**: `istanbul-reports`や`yargs`などの外部型を再利用している点に注目する。

#### Step 3: Global型を理解する

テストグローバル関数の型定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Global.ts | `packages/jest-types/src/Global.ts` | テスト関数の型定義 |

**主要処理フロー**:
- **10-55行目**: テスト関数の戻り値とコールバック型
- **57-113行目**: Each型 - パラメータ化テスト用のジェネリック型
- **122-147行目**: It/ItConcurrent型 - テスト関数のインターフェース
- **149-157行目**: Describe型 - describeブロックのインターフェース
- **159-172行目**: TestFrameworkGlobals型 - 全グローバル関数

**読解のコツ**: ジェネリック型とオーバーロードにより、配列・タプル・テンプレートリテラル等様々なテーブル形式に対応している。

#### Step 4: Circus型を理解する

jest-circusテストランナーの内部状態型を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Circus.ts | `packages/jest-types/src/Circus.ts` | テストランナー状態管理型 |

**主要処理フロー**:
- **30-37行目**: Hook型 - フック関数の状態
- **39-42行目**: EventHandler型 - イベントハンドラのシグネチャ
- **51-90行目**: SyncEvent型 - 同期イベント
- **92-191行目**: AsyncEvent型 - 非同期イベント
- **243-263行目**: State型 - テスト実行状態
- **265-274行目**: DescribeBlock型 - describeブロック構造
- **278-297行目**: TestEntry型 - 個別テストの状態

**読解のコツ**: イベント駆動型のアーキテクチャを理解するため、SyncEventとAsyncEventの各イベント名に注目する。

#### Step 5: TestResult型を理解する

テスト結果データの型を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | TestResult.ts | `packages/jest-types/src/TestResult.ts` | テスト結果の型定義 |

**主要処理フロー**:
- **8-15行目**: Status型 - テスト結果ステータス
- **23-46行目**: AssertionResult型 - アサーション結果
- **48-53行目**: SerializableError型 - シリアライズ可能なエラー

**読解のコツ**: ワーカープロセス間でシリアライズできるよう、function/symbol型の値は失われることがコメントに記載されている。

#### Step 6: Transform型を理解する

コード変換結果の型を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 6-1 | Transform.ts | `packages/jest-types/src/Transform.ts` | 変換結果の型定義 |

**主要処理フロー**:
- **9-13行目**: TransformResult型 - コード変換結果（code, originalCode, sourceMapPath）

**読解のコツ**: コメントに「巨大な依存ツリーを避けるため」とあり、軽量な型定義パッケージとしての設計意図が明記されている。

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

```
@jest/types/src/index.ts
    │
    ├─ Config.ts (設定型)
    │      ├─ @jest/pattern (TestPathPatterns)
    │      ├─ @jest/schemas (InitialOptions, SnapshotFormat)
    │      └─ 外部依存 (chalk, istanbul-reports, yargs)
    │
    ├─ Global.ts (グローバル関数型)
    │      └─ istanbul-lib-coverage (CoverageMapData)
    │
    ├─ Circus.ts (テストランナー状態型)
    │      └─ Global.ts (DoneFn, TestFn, HookFn等)
    │
    ├─ TestResult.ts (テスト結果型)
    │      └─ (外部依存なし)
    │
    └─ Transform.ts (変換結果型)
           └─ (外部依存なし)
```

### データフロー図

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

TypeScriptコンパイラ ───▶ index.ts ───▶ 型定義エクスポート
                              │
                              ├─▶ Config型 ───▶ jest設定の型チェック
                              ├─▶ Global型 ───▶ テスト関数の型チェック
                              ├─▶ Circus型 ───▶ テストランナー状態型
                              ├─▶ TestResult型 ───▶ 結果データの型チェック
                              └─▶ TransformTypes ───▶ 変換結果の型チェック
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/jest-types/src/index.ts` | ソース | エントリポイント、型の再エクスポート |
| Config.ts | `packages/jest-types/src/Config.ts` | ソース | Jest設定に関する型定義 |
| Global.ts | `packages/jest-types/src/Global.ts` | ソース | テストグローバル関数の型定義 |
| Circus.ts | `packages/jest-types/src/Circus.ts` | ソース | jest-circus状態管理型定義 |
| TestResult.ts | `packages/jest-types/src/TestResult.ts` | ソース | テスト結果データの型定義 |
| Transform.ts | `packages/jest-types/src/Transform.ts` | ソース | コード変換結果の型定義 |
| package.json | `packages/jest-types/package.json` | 設定 | パッケージメタデータ、依存関係 |
