# バッチ設計書 15-fmt

## 概要

本ドキュメントは、webpackプロジェクトにおけるnpm script `fmt` の処理内容、実行条件、入出力仕様、エラー処理等を定義するバッチ設計書である。

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

`fmt` は、Prettierによるコードフォーマットの一括実行バッチである。プロジェクト全体のファイルを `.prettierrc.js` で定義されたフォーマットルールに従って整形し、統一されたコードスタイルを維持する。`fmt:check` サブコマンドによるチェックのみの実行と、`fmt` によるファイルへの書き込み実行の2つのモードを提供する。

**業務上の目的・背景**：webpackプロジェクトでは複数の開発者がコードを変更するため、コードフォーマットの統一が必要である。Prettierを使用することで、インデント、引用符、カンマの配置、行の長さなどのフォーマットルールを自動的に適用し、コードレビュー時にフォーマットの差異に時間を費やすことを防ぐ。CI/CDパイプラインでは `fmt:check` でフォーマット違反を検出し、ローカル開発では `fmt` で自動修正を行う。

**バッチの実行タイミング**：`yarn lint` の一部として `fmt:check` が実行される（チェックのみ）。`yarn fix` の最後のステップとして `fmt` が実行される（書き込みモード）。開発者がフォーマットを整えたい場合に手動で `yarn fmt` を実行する。lint-staged経由でコミット時にも自動実行される。

**主要な処理内容**：
1. `yarn fmt:base` を呼び出し - `node node_modules/prettier/bin/prettier.cjs --cache --ignore-unknown .`
2. `fmt` モードでは `--log-level warn --write` オプションが付与され、ファイルが上書きされる
3. `fmt:check` モードでは `--check` オプションが付与され、フォーマット違反の検出のみを行う

**前後の処理との関連**：`yarn lint` の一部として `fmt:check` が実行される（`lint:code`、`lint:special`、`lint:types` の後）。`yarn fix` の最後のステップとして `fmt`（書き込みモード）が実行される（`fix:code`、`fix:special` の後）。lint-staged設定により、gitコミット時に `prettier --cache --write --ignore-unknown` が自動実行される。

**影響範囲**：`fmt` モードではプロジェクト全体のファイルが対象となる。`.prettierrc.js` の設定に従い、JavaScript（.js, .cjs, .mjs）、TypeScript（.cts, .mts, .ts）、JSON等のファイルがフォーマットされる。`--ignore-unknown` オプションにより、Prettierが対応していないファイル形式はスキップされる。`--cache` オプションにより変更のないファイルのフォーマットはスキップされる。

## バッチ種別

コードフォーマット

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時 |
| 実行時刻 | 任意 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動実行（`yarn fmt`）、`yarn fix` の一部、lint-staged（コミット時）、CI/CD（`yarn lint` 経由で `fmt:check`） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| npm依存関係インストール済み | prettier（^3.7.4）が必要 |
| .prettierrc.js 存在 | フォーマットルール定義ファイルが必要 |

### 実行可否判定

Prettierがインストールされていれば実行可能。`.prettierrc.js` が存在しない場合はPrettierのデフォルト設定が適用される。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| なし | - | - | - | 本バッチはパラメータを受け取らない。モード切替はサブコマンド（fmt / fmt:check）で行う |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| .prettierrc.js | JavaScript | Prettierフォーマットルール定義 |
| .prettierignore | テキスト | Prettier除外ファイルパターン（存在する場合） |
| プロジェクト全ファイル | 各種 | フォーマット対象ファイル群（`--ignore-unknown` により対応形式のみ処理） |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| プロジェクト内各ファイル | 各種 | フォーマットされたファイルが上書き保存される（`fmt` モード） |
| 標準出力 | テキスト | フォーマット違反のファイル一覧（`fmt:check` モード） |
| プロセス終了コード | 数値 | 0: 正常、1: フォーマット違反あり（`fmt:check` モード） |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | 対象ファイル群（フォーマットが変更されたファイルのみ上書き） |
| 出力先 | プロジェクトルートからの各ファイルパス |
| 文字コード | UTF-8 |
| 区切り文字 | 該当なし |

## 処理フロー

### 処理シーケンス

```
1. fmt:base 呼び出し
   └─ node node_modules/prettier/bin/prettier.cjs --cache --ignore-unknown .
2a. fmt モード（書き込み）
   ├─ --log-level warn: 警告以上のみ出力
   └─ --write: フォーマット結果をファイルに書き込み
2b. fmt:check モード（チェックのみ）
   └─ --check: フォーマット違反の検出のみ（ファイル変更なし）
3. .prettierrc.js のルール適用
   ├─ printWidth: 80
   ├─ useTabs: true（JSONファイルは useTabs: false）
   ├─ tabWidth: 2
   ├─ trailingComma: "none"
   ├─ arrowParens: "always"
   ├─ JSONファイル: parser: "json", useTabs: false
   └─ TypeScriptファイル: parser: "typescript"
4. キャッシュ機構
   └─ --cache により変更のないファイルをスキップ
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B{実行モード}
    B -->|fmt| C[fmt:base --log-level warn --write]
    B -->|fmt:check| D[fmt:base --check]
    C --> E[プロジェクト全ファイルを走査]
    D --> E
    E --> F{キャッシュ確認}
    F -->|キャッシュあり| G[スキップ]
    F -->|キャッシュなし| H[.prettierrc.js ルール適用]
    H --> I{フォーマット差分あり?}
    I -->|あり・fmtモード| J[ファイル上書き]
    I -->|あり・checkモード| K[違反ファイルを出力]
    I -->|なし| G
    J --> L[バッチ正常終了]
    G --> L
    K --> M[終了コード1で終了]
```

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

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

本バッチはデータベース操作を行わない。

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 該当なし | 該当なし | 該当なし | 該当なし |

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| exit 1 | フォーマット違反（checkモード） | フォーマット規定に違反するファイルが存在 | `yarn fmt` で自動修正 |
| exit 1 | パースエラー | Prettierが解析できないファイル構文エラー | 対象ファイルの構文エラーを修正 |
| exit 2 | Prettier設定エラー | .prettierrc.jsの構文エラー | 設定ファイルを修正 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（リトライなし） |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

### 障害時対応

フォーマット違反の場合は `yarn fmt` で自動修正する。パースエラーの場合は、エラーメッセージに表示されるファイルの構文エラーを修正する。設定ファイルのエラーの場合は `.prettierrc.js` を修正する。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし（データベース操作なし） |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし（ファイル変更のロールバックはgit restoreで対応） |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | プロジェクト内の全対象ファイル（数百〜数千ファイル） |
| 目標処理時間 | --cache使用により初回以降は数秒〜数十秒 |
| メモリ使用量上限 | デフォルトのNode.jsヒープ上限（約1.5GB） |

## 排他制御

同一プロジェクトディレクトリ内での同時実行は推奨されない。`fmt` モードではファイルの上書きが発生するため、他のファイル操作と競合する可能性がある。`fmt:check` モードは読み取り専用のため、同時実行による問題は発生しない。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 進捗ログ | fmt実行時 | フォーマットされたファイル一覧（--log-level warn により警告以上のみ） |
| エラーログ | パースエラー時 | パースエラーのファイル名と行番号 |
| 結果ログ | fmt:check実行時 | フォーマット違反のファイル一覧 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| プロセス終了コード | != 0（fmt:checkモード） | CI/CDパイプライン |

## 備考

- `.prettierrc.js` の主要設定：`printWidth: 80`、`useTabs: true`、`tabWidth: 2`、`trailingComma: "none"`、`arrowParens: "always"`。
- JSONファイル用のオーバーライド設定：`parser: "json"`、`useTabs: false`（JSONファイルではスペースインデント）。
- TypeScriptファイル用のオーバーライド設定：`parser: "typescript"`（`.cts`、`.mts`、`.ts`ファイル）。
- Prettier 3系（^3.7.4）を使用。prettier-2（npm:prettier@^2）もdevDependenciesに含まれているが、これはJestの `prettierPath` 設定で使用されるもので、`fmt` スクリプトとは別系統である。
- lint-staged設定（package.json内）では、`*.{js,cjs,mjs}` に対してESLint、全ファイルに対してPrettierとcspellが設定されており、コミット時に自動フォーマットが適用される。
- `--ignore-unknown` オプションにより、Prettierが対応していないファイル形式（バイナリファイル等）は自動的にスキップされる。
- `--cache` オプションにより、変更のないファイルのフォーマット処理がスキップされ、再実行時のパフォーマンスが向上する。
