# 機能設計書 50-@jest/schemas

## 概要

本ドキュメントは、@jest/schemasパッケージの機能設計について記載する。このパッケージは、Jest設定のスキーマ定義を提供し、TypeBoxを使用した型安全な設定バリデーションを実現する。

### 本機能の処理概要

@jest/schemasは、Jestの設定オプションをTypeBoxスキーマとして定義する。これにより、実行時のバリデーションと静的な型推論の両方を提供する。

**業務上の目的・背景**：Jestには多数の設定オプションがあり、それぞれに適切な型と値の範囲がある。@jest/schemasは、これらの設定をスキーマとして定義することで、設定ファイルの検証、IDEでのコード補完、ドキュメント生成を統一的に管理できるようにする。TypeBoxを使用することで、JSONスキーマとTypeScript型の両方を1つの定義から生成できる。

**機能の利用シーン**：Jest設定ファイル（jest.config.js/ts）の検証、jest-validateパッケージでのバリデーション、IDE補完のための型情報提供などに使用される。

**主要な処理内容**：
1. InitialOptions: Jest全体の設定スキーマ
2. SnapshotFormat: スナップショットの表示形式スキーマ
3. FakeTimers: フェイクタイマーの設定スキーマ
4. TypeBoxによるスキーマ定義: Type.Object、Type.Union等を使用

**関連システム・外部連携**：@sinclair/typebox（スキーマ定義ライブラリ）を使用。

**権限による制御**：特になし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 22 | Configurationページ | 主機能 | Jest設定オプションの詳細説明 |

## 機能種別

スキーマ定義 / 型定義

## 入力仕様

### 入力パラメータ

該当なし（スキーマ定義のエクスポートのみ）

### 入力データソース

該当なし

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| InitialOptions | TObject | Jest初期設定のスキーマ |
| SnapshotFormat | TObject | スナップショット形式のスキーマ |
| FakeTimers | TIntersect | フェイクタイマーのスキーマ |

### 出力先

- モジュールエクスポート

## 処理フロー

### 処理シーケンス

```
1. raw-types.tsでスキーマ定義
   └─ TypeBoxのType.*関数でスキーマを構築
2. index.tsでエクスポート
   └─ スキーマとStatic型の両方をエクスポート
3. 利用側での使用
   └─ スキーマを使用してバリデーション
   └─ 型を使用してTypeScript型チェック
```

### フローチャート

```mermaid
flowchart TD
    A[raw-types.ts] --> B[InitialOptions定義]
    A --> C[SnapshotFormat定義]
    A --> D[FakeTimers定義]
    B --> E[index.ts]
    C --> E
    D --> E
    E --> F[スキーマエクスポート]
    E --> G[Static型エクスポート]
    F --> H[バリデーション使用]
    G --> I[TypeScript型チェック]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-50-01 | 部分適用 | Type.Partialで全プロパティをオプショナルに | InitialOptions |
| BR-50-02 | 数値範囲 | coverageThresholdは0-100の範囲 | カバレッジ設定 |
| BR-50-03 | Union型 | coverageProviderは'babel'または'v8' | カバレッジ設定 |
| BR-50-04 | 整数制限 | indentやmaxDepthはType.Integer({minimum: 0}) | SnapshotFormat |

### 計算ロジック

該当なし（スキーマ定義のみ）

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

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

該当なし（データベース操作は行わない）

## エラー処理

### エラーケース一覧

該当なし（スキーマ定義のみ）

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

該当なし

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

- スキーマ定義のみで、ユーザー入力の処理は行わない

## 備考

- TypeBoxはJSON SchemaとTypeScript型の両方を生成可能
- Static<typeof Schema>で型を抽出

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `packages/jest-schemas/src/index.ts` | エクスポート構造 |

**主要処理フロー**:
- **8-9行目**: @sinclair/typeboxからStaticをインポート
- **11-18行目**: 各スキーマとその型をエクスポート

**読解のコツ**: TypeBoxのStatic<typeof T>は、スキーマTからTypeScript型を抽出する。

#### Step 2: SnapshotFormatスキーマを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | raw-types.ts | `packages/jest-schemas/src/raw-types.ts` | SnapshotFormat定義（12-35行目） |

**主要プロパティ**:
- **14行目**: callToJSON - Type.Boolean()
- **19行目**: indent - Type.Integer({minimum: 0})
- **20行目**: maxDepth - Type.Integer({minimum: 0})
- **25-33行目**: theme - ネストされたType.Partial(Type.Object(...))

#### Step 3: FakeTimersスキーマを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | raw-types.ts | `packages/jest-schemas/src/raw-types.ts` | FakeTimers定義（115-189行目） |

**主要プロパティ**:
- **117-123行目**: GlobalFakeTimersConfig - enableGlobally
- **125-141行目**: FakeableAPI - Dateやhrtime等のUnion
- **143-174行目**: FakeTimersConfig - advanceTimers、doNotFake等
- **186-189行目**: Type.IntersectでGlobalとConfig/Legacyを合成

#### Step 4: InitialOptionsスキーマを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | raw-types.ts | `packages/jest-schemas/src/raw-types.ts` | InitialOptions定義（228-355行目） |

**主要プロパティ**:
- **231行目**: automock - Type.Boolean()
- **242行目**: coverageProvider - Type.Union([Type.Literal('babel'), Type.Literal('v8')])
- **251行目**: fakeTimers - FakeTimersスキーマを参照
- **322行目**: testEnvironment - Type.String()
- **352行目**: workerThreads - Type.Boolean()

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

```
index.ts
    │
    ├─ import * as types from './raw-types'
    │
    ├─ export SnapshotFormat = types.SnapshotFormat
    │      └─ type SnapshotFormat = Static<typeof SnapshotFormat>
    │
    ├─ export InitialOptions = types.InitialOptions
    │      └─ type InitialOptions = Static<typeof InitialOptions>
    │
    └─ export FakeTimers = types.FakeTimers
           └─ type FakeTimers = Static<typeof FakeTimers>

raw-types.ts
    │
    ├─ SnapshotFormat = Type.Partial(Type.Object({...}))
    │
    ├─ CoverageProvider = Type.Union([Type.Literal('babel'), Type.Literal('v8')])
    │
    ├─ FakeTimers = Type.Intersect([GlobalFakeTimersConfig, Type.Union([...])])
    │
    ├─ HasteConfig = Type.Partial(Type.Object({...}))
    │
    └─ InitialOptions = Type.Partial(Type.Object({...}))
           │
           ├─ fakeTimers: FakeTimers
           ├─ haste: HasteConfig
           ├─ coverageProvider: CoverageProvider
           └─ snapshotFormat: SnapshotFormat
```

### データフロー図

```
[定義]                    [エクスポート]                 [使用]

TypeBox Type.*関数 ─────▶ raw-types.ts ────────────────▶ スキーマオブジェクト
                              │
                              ▼
                         index.ts
                              │
                              ├─ スキーマ ─────────────▶ バリデーション
                              │                           └─ TypeBox Compile/Check
                              │
                              └─ Static<typeof T> ────▶ TypeScript型
                                                          └─ 型チェック/補完
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/jest-schemas/src/index.ts` | ソース | エントリーポイント |
| raw-types.ts | `packages/jest-schemas/src/raw-types.ts` | ソース | スキーマ定義 |

### 主要な設定オプション一覧

以下はInitialOptionsで定義されている主要な設定オプション:

| カテゴリ | オプション | 型 | 説明 |
|---------|-----------|-----|------|
| 基本 | rootDir | string | プロジェクトルート |
| 基本 | testMatch | string \| string[] | テストファイルパターン |
| カバレッジ | collectCoverage | boolean | カバレッジ収集 |
| カバレッジ | coverageProvider | 'babel' \| 'v8' | カバレッジプロバイダー |
| 環境 | testEnvironment | string | テスト環境 |
| タイマー | fakeTimers | FakeTimers | フェイクタイマー設定 |
| 並列 | maxWorkers | string \| number | ワーカー数 |
| スナップショット | snapshotFormat | SnapshotFormat | スナップショット形式 |
