# バッチ設計書 21-prettier.cjs

## 概要

本ドキュメントは、Prettierプロジェクトの CLI（コマンドラインインターフェース）エントリーポイントである `prettier.cjs` の設計を記載したものです。

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

`prettier.cjs` は、Prettierをコマンドラインから実行するためのメインエントリーポイントです。ユーザーが `npx prettier` や `prettier` コマンドを実行した際に、このスクリプトが起動点となり、ソースコードのフォーマット処理を開始します。

**業務上の目的・背景**：開発者がコマンドラインからPrettierを直接実行し、ソースコードを自動フォーマットするための統一されたインターフェースを提供します。このスクリプトにより、CI/CDパイプライン、エディタ統合、pre-commitフック、手動実行など、様々なワークフローでPrettierを利用可能にします。Node.jsバージョンの互換性チェックやコンパイルキャッシュの有効化など、実行環境の最適化も担います。

**バッチの実行タイミング**：随時実行（オンデマンド）。ユーザーがコマンドラインからprettierコマンドを実行した時、CI/CDパイプラインでのコードチェック時、pre-commitフック実行時、エディタからの呼び出し時など。

**主要な処理内容**：
1. Node.jsのコンパイルキャッシュを有効化してパフォーマンスを向上
2. Node.jsバージョンが最低要件（20以上）を満たしているかチェックし、不足時はアップグレードを促すメッセージを表示
3. 環境変数 `PRETTIER_EXPERIMENTAL_CLI` または `--experimental-cli` フラグの有無を判定
4. 通常モード（`src/cli/index.js`）または実験的CLI（`@prettier/cli`）のいずれかを動的にインポートして実行
5. CLIの実行結果をPromiseとして外部に公開（テスト用途）

**前後の処理との関連**：このスクリプトは独立したエントリーポイントであり、前提となるバッチはありません。後続処理として、`src/cli/index.js` または `src/experimental-cli/index.js` が呼び出され、実際のフォーマット処理が実行されます。

**影響範囲**：プロジェクト内のすべてのソースファイル（対象言語・拡張子に該当するもの）。標準入出力、ファイルシステム、終了コード。

## バッチ種別

CLI実行 / コマンドラインツール / コードフォーマッター

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（オンデマンド） |
| 実行時刻 | 任意 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動 / CI / pre-commitフック / エディタ統合 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Node.js 20以上 | package.jsonの `engines.node` で `>=20` が指定されている |
| npmパッケージのインストール | `please-upgrade-node` など依存パッケージが利用可能であること |

### 実行可否判定

- Node.jsのバージョンが要件を満たさない場合、`please-upgrade-node` パッケージによりアップグレードを促すメッセージが表示され、処理が中断される
- 環境変数 `PRETTIER_EXPERIMENTAL_CLI` が設定されているか、`--experimental-cli` フラグが指定されている場合は実験的CLIモードで実行
- それ以外は標準CLIモードで実行

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| --experimental-cli | flag | No | false | 実験的CLIモードを有効化 |
| --version, -v | flag | No | false | バージョン番号を表示 |
| --help, -h | flag | No | false | ヘルプメッセージを表示 |
| --check, -c | flag | No | false | フォーマット済みかチェック |
| --write, -w | flag | No | false | ファイルを直接上書き |
| --list-different, -l | flag | No | false | 差分のあるファイル一覧を表示 |
| --config | path | No | 自動検出 | 設定ファイルのパス |
| --ignore-path | path | No | .gitignore, .prettierignore | 無視パターンファイルのパス |
| --cache | flag | No | false | 変更ファイルのみフォーマット |
| --cache-location | path | No | 自動 | キャッシュファイルのパス |
| --cache-strategy | choice | No | content | キャッシュ戦略（metadata/content） |
| --log-level | choice | No | log | ログレベル（silent/error/warn/log/debug） |
| [file/dir/glob...] | string[] | No | - | 対象ファイル・ディレクトリ・globパターン |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| process.argv | CLI引数 | コマンドライン引数 |
| process.stdin | 標準入力 | パイプ経由のソースコード入力 |
| ファイルシステム | ソースファイル | フォーマット対象のソースコード |
| .prettierrc / prettier.config.js | JSON/JS/YAML | Prettier設定ファイル |
| .prettierignore / .gitignore | テキスト | 無視パターン定義 |
| .editorconfig | INI | エディタ設定（オプション） |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| process.stdout | テキスト | フォーマット済みコード / ファイル一覧 / バージョン / ヘルプ |
| process.stderr | テキスト | エラーメッセージ / 警告 / デバッグ情報 |
| ファイルシステム | ソースファイル | --write オプション時にフォーマット済みコードを上書き保存 |
| process.exitCode | 数値 | 終了コード（0: 成功, 1: チェック失敗, 2: エラー） |

### 出力ファイル仕様

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

## 処理フロー

### 処理シーケンス

```
1. Node.jsコンパイルキャッシュの有効化
   └─ nodeModule.enableCompileCache() を呼び出し（利用可能な場合のみ）
2. Node.jsバージョンチェック
   └─ please-upgrade-nodeパッケージでバージョン確認、不足時はエラーメッセージ表示
3. 実行モード判定
   └─ PRETTIER_EXPERIMENTAL_CLI環境変数または--experimental-cliフラグを確認
4. CLIモジュールの動的インポート
   └─ 標準CLI: src/cli/index.js / 実験的CLI: src/experimental-cli/index.js
5. CLI実行
   └─ cli.run() または cli.__promise を呼び出し
6. 結果のPromise公開
   └─ テスト用に module.exports.__promise として公開
```

### フローチャート

```mermaid
flowchart TD
    A[prettier.cjs 開始] --> B{enableCompileCache 利用可能?}
    B -->|Yes| C[コンパイルキャッシュ有効化]
    B -->|No| D[スキップ]
    C --> E[Node.jsバージョンチェック]
    D --> E
    E --> F{バージョン要件満たす?}
    F -->|No| G[アップグレード促進メッセージ表示]
    G --> H[終了]
    F -->|Yes| I{experimental-cli モード?}
    I -->|Yes| J[experimental-cli/index.js をインポート]
    I -->|No| K[cli/index.js をインポート]
    J --> L[cli.__promise を取得]
    K --> M[cli.run を実行]
    L --> N[Promise を公開]
    M --> N
    N --> O[終了]
```

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

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

本バッチはデータベースを使用しません。

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| N/A | N/A | N/A | データベース操作なし |

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| Exit 1 | フォーマット差分 | --check / --list-different でフォーマットされていないファイルを検出 | --write オプションで自動修正 |
| Exit 2 | 実行時エラー | ファイル読み取り失敗、パースエラー、設定エラーなど | エラーメッセージを確認し原因を修正 |
| N/A | UndefinedParserError | 対応するパーサーが見つからないファイル | --ignore-unknown オプションで無視、または対応プラグインを追加 |
| N/A | ConfigError | 設定ファイルの形式エラー | .prettierrc などの設定ファイルを修正 |

### リトライ仕様

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

### 障害時対応

- パースエラー: エラーメッセージに表示されるファイル名と行番号を確認し、構文エラーを修正
- 設定エラー: 設定ファイル（.prettierrc等）の形式を確認
- ファイルアクセスエラー: ファイルの存在とパーミッションを確認

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | N/A（データベース不使用） |
| コミットタイミング | N/A |
| ロールバック条件 | N/A |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 数千ファイル程度 |
| 目標処理時間 | ファイル数に依存（キャッシュ有効時は高速化） |
| メモリ使用量上限 | Node.jsデフォルトヒープサイズ |

## 排他制御

- 同一ファイルへの同時書き込みは想定されていない
- --cache オプション使用時はキャッシュファイルへのアクセスがある
- 大規模プロジェクトでの並列実行は別プロセスで行う設計

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | --check時 | "Checking formatting..." |
| 進捗ログ | ファイル処理中（TTY時） | ファイル名（処理中のファイル） |
| 終了ログ | --check完了時 | "All matched files use Prettier code style!" / 差分ファイル数 |
| エラーログ | エラー発生時 | エラーメッセージ（ファイル名、行番号、エラー詳細） |
| デバッグログ | --log-level=debug時 | 正規化された引数、パフォーマンス測定結果など |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 終了コード | 0以外 | CI/CDシステムのジョブ失敗通知 |
| 処理時間 | プロジェクト依存 | CI/CDのタイムアウト設定 |

## 備考

- `--experimental-cli` オプションまたは `PRETTIER_EXPERIMENTAL_CLI` 環境変数により、`@prettier/cli` パッケージの実験的CLIを使用可能
- Node.js 22以降では `nodeModule.enableCompileCache()` によるコンパイルキャッシュが有効になり、起動時間が短縮される
- `module.exports.__promise` はテスト用に公開されており、非同期処理の完了を待機可能
- package.jsonの `bin` フィールドにより、このファイルがnpmパッケージのCLIエントリーポイントとして登録される
