# バッチ設計書 16-format

## 概要

本ドキュメントは、Decap CMSプロジェクトにおけるコード自動フォーマットバッチ `format` の設計仕様を定義する。本バッチはESLintの自動修正（--fix）とPrettierによるコードフォーマット（--write）を順次実行し、コードスタイルを自動的に統一する。

### 本バッチの処理概要

本バッチは、Decap CMSモノレポ全体のコードを自動的にフォーマットするスクリプトである。まずESLintの自動修正を実行し、次にPrettierによるフォーマットを適用する。リントエラーの修正とコードスタイルの統一を一括で行える便利なコマンドである。

**業務上の目的・背景**：No.15 lint で検出されたスタイル違反やフォーマット不整合を自動修正するために使用する。手動での修正が面倒な大量のフォーマットエラーを一括修正でき、開発者の生産性を向上させる。コードレビュー前に実行することで、スタイルに関する指摘を事前に排除できる。

**バッチの実行タイミング**：開発者による手動実行（随時）。lint失敗後の修正手段として、またはコミット前のコード整形として使用される。

**主要な処理内容**：
1. `npm run lint:js -- --fix --quiet` - ESLintの自動修正をquietモードで実行（修正可能なルール違反を自動修正）
2. `npm run format:prettier -- --write` - Prettierでコードフォーマットを適用してファイルを上書き

**前後の処理との関連**：No.15 lint でリントエラーが検出された場合の修正手段として使用される。本バッチ実行後に No.15 lint を再実行して修正結果を確認することが推奨される。

**影響範囲**：packages/ および scripts/ 配下のJS/JSX/TS/TSX/CSSファイルが変更対象となる。ファイルの内容が直接書き換えられるため、事前にgit stageまたはcommitしておくことが推奨される。

## バッチ種別

コードフォーマット（自動修正・スタイル統一）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時 |
| 実行時刻 | 任意 |
| 実行曜日 | なし |
| 実行日 | なし |
| トリガー | 手動（開発者によるローカル実行） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Node.js | Node.js 22.x または 24.x がインストールされていること |
| 依存パッケージ | `npm ci` または `npm install` で依存関係がインストール済みであること |
| 設定ファイル | .eslintrc.js, .prettierrc が存在すること |

### 実行可否判定

特別な実行可否判定は行わない。前提条件が満たされていれば常に実行可能である。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| なし | - | - | - | 本バッチは入力パラメータを取らない |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| {packages,scripts}/**/*.{js,jsx,ts,tsx} | ソースコード | ESLint自動修正対象ファイル |
| {packages,scripts}/**/*.{js,jsx,ts,tsx,css} | ソースコード | Prettierフォーマット対象ファイル |
| .eslintrc.js | 設定ファイル | ESLint設定（自動修正可能なルール定義） |
| .prettierrc | 設定ファイル | Prettier設定 |
| .gitignore | 設定ファイル | ESLint除外パターン |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| ソースファイル（上書き） | JS/JSX/TS/TSX/CSS | フォーマット適用済みのソースコード |
| 標準出力 | テキスト | フォーマット処理のログ |
| プロセス終了コード | 数値 | 0: 成功、1以上: 自動修正不可能なエラー |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | 入力ファイルと同名（上書き） |
| 出力先 | 入力ファイルと同じパス |
| 文字コード | UTF-8 |
| 区切り文字 | N/A |

## 処理フロー

### 処理シーケンス

```
1. ESLint自動修正
   └─ eslint --color --ignore-path .gitignore "{{packages,scripts}/**/,}*.{js,jsx,ts,tsx}" --fix --quiet
       ├─ 自動修正可能なルール違反を修正してファイルを上書き
       └─ quietモードでエラーのみ出力
2. Prettierフォーマット
   └─ prettier "{{packages,scripts}/**/,}*.{js,jsx,ts,tsx,css}" --write
       └─ Prettierルールに従ってフォーマットし、ファイルを上書き
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始: npm run format] --> B[ESLint --fix --quiet 実行]
    B --> C{ESLint修正成功?}
    C -->|自動修正不可エラー| Z[エラー終了]
    C -->|成功| D[Prettier --write 実行]
    D --> E{Prettierフォーマット成功?}
    E -->|失敗| Z
    E -->|成功| F[バッチ正常終了]
```

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

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

本バッチはデータベースへのアクセスを行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | ESLint自動修正不可 | --fixでは修正できないルール違反が存在 | 手動でコードを修正 |
| 1 | Prettierパースエラー | 構文エラーのあるファイルが存在 | 構文エラーを手動で修正後に再実行 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし（手動再実行） |
| リトライ間隔 | なし |
| リトライ対象エラー | なし |

### 障害時対応

ESLintの自動修正で対応できないエラーは手動修正が必要。Prettierのパースエラーは対象ファイルの構文エラーを先に修正する。フォーマット結果が意図しないものだった場合は、`git checkout` や `git stash` で変更を元に戻すことができる。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | なし（ファイル個別書き換え） |
| コミットタイミング | なし |
| ロールバック条件 | git操作で手動ロールバック |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | packages/およびscripts/配下の全対象ファイル |
| 目標処理時間 | 1分以内 |
| メモリ使用量上限 | Node.jsデフォルトヒープサイズ |

## 排他制御

ファイルを直接書き換えるため、同時に複数のformatプロセスを実行すべきではない。また、エディタで編集中のファイルとの競合にも注意が必要。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 進捗ログ | ESLint実行中 | 自動修正の進捗（quietモードのためエラーのみ） |
| 進捗ログ | Prettier実行中 | フォーマット対象ファイルの一覧 |
| エラーログ | エラー発生時 | 自動修正不可能なエラーの詳細 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 処理時間 | なし（ローカル実行のため） | なし |
| エラー件数 | なし（ローカル実行のため） | なし |

## 備考

- 本バッチは `npm run format` コマンドで実行される
- ESLintの --fix オプションは自動修正可能なルールのみを対象とする（手動修正が必要なルール違反は残る）
- Prettierの --write オプションによりファイルが直接上書きされるため、事前のgit stageが推奨される
- format:prettier サブコマンド（`prettier "{{packages,scripts}/**/,}*.{js,jsx,ts,tsx,css}"`）が内部で使用される
- ESLint実行は --quiet オプション付きで、エラーのみを出力する
