# 通知設計書 32-cache-cannot-be-used-when-formatting-stdin

## 概要

本ドキュメントは、Prettier CLIにおいて標準入力（stdin）からのフォーマット時に `--cache` オプションが使用された場合に発生するエラー通知「--cache cannot be used when formatting stdin」の設計仕様を記載する。

### 本通知の処理概要

本通知は、標準入力フォーマットモードにおいてキャッシュオプションが不正に使用された場合にユーザーに警告し、適切なオプションの使用を促すエラーメッセージを出力する機能を提供する。

**業務上の目的・背景**：Prettierのキャッシュ機能はファイルベースで動作し、ファイルパスとその内容またはメタデータをキーとしてフォーマット結果をキャッシュする。標準入力からのフォーマットは一時的なデータストリームであり、キャッシュの対象として適切でない。このエラー通知により、ユーザーがキャッシュ機能の技術的制約を理解し、正しい使用方法を把握できるようにする。

**通知の送信タイミング**：CLIの実行モード判定後、標準入力フォーマットが選択された時点で`--cache`オプションの有無がチェックされる。`formatStdin`関数の呼び出し直前にエラーが発生する。

**通知の受信者**：Prettier CLIを実行しているユーザー（開発者）。パイプやリダイレクトでPrettierにコードを渡す使用ケースで発生する。

**通知内容の概要**：「`--cache` cannot be used when formatting stdin.」というエラーメッセージが出力される。バックティックでオプション名が囲まれ、視認性を高めている。

**期待されるアクション**：ユーザーは以下のいずれかの対応を行うことが期待される：
1. `--cache`オプションを削除して再実行する
2. ファイルパスを指定してファイルベースのフォーマットに切り替える

## 通知種別

CLI標準エラー出力（stderr）へのエラーメッセージ

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期 |
| 優先度 | 高 |
| リトライ | 無し |

### 送信先決定ロジック

CLIを実行したプロセスの標準エラー出力に直接出力される。ロガーの`error`メソッドを経由し、`[error]`プレフィックス付きで赤色表示される。

## 通知テンプレート

### CLI出力の場合

| 項目 | 内容 |
|-----|------|
| 出力先 | stderr |
| プレフィックス | [error] |
| 色 | 赤（red） |

### 本文テンプレート

```
[error] `--cache` cannot be used when formatting stdin.
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| なし | 固定メッセージのため変数なし | - | - |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| CLI実行 | stdin入力検出後のオプション検証 | `useStdin && context.argv.cache` | stdinモードで--cacheが指定されている場合 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| ファイルパターンが指定されている場合 | ファイルモードのため抑止 |
| `--cache`が未指定の場合 | 検証対象外のため抑止 |
| TTYかつfilepathオプション未指定の場合 | stdinモードではないため抑止 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[CLI起動] --> B[オプション解析]
    B --> C{ファイルパターン<br>が存在する?}
    C -->|Yes| D[ファイルモード]
    C -->|No| E{stdin入力あり<br>または--filepath指定?}
    E -->|No| F[ヘルプ表示]
    E -->|Yes| G{--cacheが<br>指定されている?}
    G -->|No| H[formatStdin実行]
    G -->|Yes| I[エラー通知生成]
    I --> J[logger.error呼び出し]
    J --> K[stderrへ出力]
    K --> L[プロセス終了コード1]
    L --> M[終了]
```

## データベース参照・更新仕様

### 参照テーブル一覧

該当なし（CLIツールのためデータベースは使用しない）

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| stdin/キャッシュ競合 | stdin入力時に--cacheを指定 | エラーメッセージを出力して終了 |

### リトライ仕様

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

## 配信設定

### レート制限

該当なし（CLI同期処理のため）

### 配信時間帯

該当なし（CLI実行時即座に出力）

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

本エラー通知は固定メッセージのみを出力し、ユーザー入力やファイル内容を含まないため、セキュリティ上の考慮事項は特にない。

## 備考

- 標準入力モードは以下の条件で有効化される：
  1. ファイルパターンが指定されていない
  2. 標準入力がTTYでない（パイプ入力など）、または`--filepath`オプションが指定されている
- `--filepath`オプションはstdin入力のファイルパスを仮定して適切なパーサーを選択するために使用される
- stdinモードでもキャッシュを使用したい場合は、一時ファイルに書き出してからファイルモードで実行する回避策がある

---

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

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

### 推奨読解順序

#### Step 1: データ構造を理解する

CLIオプションとstdinモード判定に必要なデータを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | cli-options.evaluate.js | `src/cli/cli-options.evaluate.js` | cacheオプションの定義（64-68行目） |
| 1-2 | context.js | `src/cli/context.js` | argvとfilePatterns（39-40行目） |

**読解のコツ**: `filePatterns`は`argv._`（位置引数）から取得される。これがstdin/ファイルモード判定に使用される。

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

stdinモード判定とエラーチェックの場所を特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.js | `src/cli/index.js` | useStdin判定とcacheチェック（97-108行目） |

**主要処理フロー**:
1. **97行目**: `hasFilePatterns`で位置引数の有無を確認
2. **98-100行目**: `useStdin`条件の算出（パターンなし＆非TTYまたはfilepath指定）
3. **102-105行目**: useStdinかつcache指定時のエラー発生
4. **107行目**: `formatStdin(context)`の呼び出し（正常時）

#### Step 3: stdinフォーマット処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | format.js | `src/cli/format.js` | formatStdin関数の実装（225-270行目） |

**主要処理フロー**:
- **229行目**: `getStdin()`で標準入力を取得
- **233行目**: filepath指定時は絶対パスに変換
- **256行目**: `format`関数でフォーマット実行

#### Step 4: TTY判定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | mockable.js | `src/cli/mockable.js` | isStreamTTY関数（テスト用モック可能） |

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

```
run (src/cli/index.js:13)
    │
    ├─ Context.init (src/cli/context.js:29)
    │      └─ argv._ → filePatterns
    │
    └─ main (src/cli/index.js:39)
           │
           ├─ hasFilePatterns判定 (97行目)
           │
           ├─ useStdin判定 (98-100行目)
           │      ├─ !hasFilePatterns
           │      └─ !isStreamTTY(stdin) || argv.filepath
           │
           └─ if (useStdin && argv.cache)
                  └─ throw new Error (104行目)
                         │
                         └─ catch → logger.error (34行目)
```

### データフロー図

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

CLI引数
--cache              Context初期化
  │                      ↓
  │                  argv.cache = true
  │                      ↓
stdin入力 ───────▶  useStdin = true
                        ↓
                  useStdin && cache
                        ↓
                  Error生成 ───────▶ stderr: [error] メッセージ
                        ↓
                  process.exitCode = 1
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.js | `src/cli/index.js` | ソース | CLIエントリーポイント、stdin/cache競合検証 |
| format.js | `src/cli/format.js` | ソース | formatStdin関数（実際のstdinフォーマット処理） |
| context.js | `src/cli/context.js` | ソース | CLIコンテキスト管理、argv/filePatterns格納 |
| logger.js | `src/cli/logger.js` | ソース | ログ出力機能（error/warn/log/debug） |
| cli-options.evaluate.js | `src/cli/cli-options.evaluate.js` | ソース | CLIオプション定義 |
| mockable.js | `src/cli/mockable.js` | ソース | テスト用モック可能関数（isStreamTTY等） |
