# 画面設計書 15-Usage-CLI

## 概要

本ドキュメントは、Prettierドキュメントサイトの「Usage - CLI」画面の設計書です。この画面はPrettierのコマンドラインインターフェース（CLI）の使用方法を包括的に説明するドキュメントページです。

### 本画面の処理概要

この画面はPrettier CLIの全オプションと使用方法を詳細に説明する静的ドキュメントページです。ファイルフォーマット、フォーマットチェック、設定ファイル検索、キャッシュ機能など、コマンドラインからPrettierを操作するための全機能を解説しています。

**業務上の目的・背景**：開発者の多くはコマンドラインからPrettierを実行します。CI/CDパイプライン、ビルドスクリプト、タスクランナーとの統合など、様々なシナリオでCLI操作が必要となります。この画面は、CLIの全オプションを網羅的に説明し、開発者が効率的にPrettierを活用できるようにします。

**画面へのアクセス方法**：ユーザーはメインサイトのナビゲーションバーから「Docs」セクションに入り、サイドバーの「Usage」カテゴリ内の「CLI」リンクをクリックしてアクセスします。URLは `/docs/cli` です。

**主要な操作・処理内容**：
1. 基本的なフォーマットコマンド（`prettier . --write`）の理解
2. ファイルパターン指定方法の理解
3. `--check`/`--list-different`オプションによるフォーマットチェック
4. `--find-config-path`/`--config`による設定ファイル指定
5. `--cache`によるパフォーマンス最適化
6. `--ignore-path`による除外設定
7. 標準入力からのフォーマット（`--stdin-filepath`）

**画面遷移**：この画面からはIgnoreドキュメント、設定ファイルドキュメント、pre-commitドキュメント、エディタ連携ドキュメント、プラグインドキュメントへのリンクが設定されています。

**権限による表示制御**：なし。全ユーザーが同一のコンテンツを閲覧可能。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 17 | ファイルフォーマット（--write） | 主機能 | CLIでのファイルフォーマット実行方法を説明 |
| 18 | フォーマットチェック（--check） | 補助機能 | CLIでのフォーマットチェック方法を説明 |
| 19 | 差分表示（--list-different） | 補助機能 | CLIでの差分ファイル一覧表示を説明 |
| 20 | 標準入力フォーマット | 補助機能 | CLIでの標準入力フォーマット方法を説明 |
| 21 | フォーマットキャッシュ（--cache） | 補助機能 | CLIでのキャッシュ機能を説明 |
| 22 | Ignoreファイル処理（--ignore-path） | 補助機能 | CLIでの無視パス指定を説明 |
| 23 | ファイル情報取得（--file-info） | 補助機能 | CLIでのファイル情報取得を説明 |
| 24 | サポート情報表示（--support-info） | 補助機能 | CLIでのサポート情報表示を説明 |
| 25 | ヘルプ表示（--help） | 補助機能 | CLIでのヘルプ表示を説明 |
| 26 | バージョン表示（--version） | 補助機能 | CLIでのバージョン表示を説明 |
| 67 | AST出力（--debug-print-ast） | 補助機能 | CLIでのデバッグAST出力を説明 |
| 68 | Doc出力（--debug-print-doc） | 補助機能 | CLIでのデバッグDoc出力を説明 |
| 69 | ベンチマーク（--debug-benchmark） | 補助機能 | CLIでのベンチマーク機能を説明 |
| 70 | 整合性チェック（--debug-check） | 補助機能 | CLIでの整合性チェック機能を説明 |

## 画面種別

ドキュメント / 参照

## URL/ルーティング

- **URL**: `/docs/cli`
- **ソースファイル**: `docs/cli.md`
- **生成方式**: Docusaurus docs機能によるMarkdownからの静的HTML生成

## 入出力項目

本画面は静的ドキュメントページのため、ユーザー入力フィールドはありません。

## 表示項目

| セクション | 表示内容 | 説明 |
|-----------|---------|------|
| 基本コマンド | prettier [options] [file/dir/glob ...] | 基本的なコマンド構文 |
| File patterns | ファイルパターン | glob構文でのファイル指定方法 |
| --check | フォーマットチェック | 差分検出と終了コード |
| --debug-check | 整合性チェック | コード正確性のチェック |
| --find-config-path / --config | 設定ファイル | 設定ファイルの検索と指定 |
| --ignore-path | 無視パス | 除外パターンファイルの指定 |
| --list-different | 差分一覧 | 未フォーマットファイル一覧 |
| --no-config | 設定無効化 | 設定ファイルを無視 |
| --config-precedence | 優先順位 | CLI vs 設定ファイルの優先度 |
| --no-editorconfig | EditorConfig無効化 | .editorconfigを無視 |
| --with-node-modules | node_modules含む | node_modules内も処理 |
| --write | ファイル上書き | フォーマット結果でファイル更新 |
| --log-level | ログレベル | 出力の詳細度設定 |
| --stdin-filepath | 標準入力パス | stdinのファイル名指定 |
| --ignore-unknown | 不明ファイル無視 | 未対応ファイルをスキップ |
| --cache系 | キャッシュ設定 | cache, cache-location, cache-strategy |
| Exit codes | 終了コード | 0: 成功, 1: 差分あり, 2: エラー |

## イベント仕様

### 1-アンカーリンククリック

ドキュメント内のアンカーリンクをクリックすると、対応するセクションにスクロールします。

### 2-内部リンククリック

- `ignore.md` → Ignoreドキュメント
- `configuration.md` → 設定ファイルドキュメント
- `precommit.md` → pre-commitドキュメント
- `editors.md` → エディタ連携ドキュメント
- `plugins.md` → プラグインドキュメント
- `api.md` → APIドキュメント

## データベース更新仕様

本画面は静的ドキュメントページのため、データベース更新は発生しません。

## メッセージ仕様

本画面は静的ドキュメントページのため、動的メッセージはありません。

## 例外処理

| 状態 | 説明 |
|------|------|
| ページ未発見（404） | URLが誤っている場合、Docusaurus標準の404ページを表示 |

## 備考

- `npx prettier --help`、`yarn exec prettier --help`等の実行方法が冒頭で説明されている
- ファイルパターンはquotesで囲むことが推奨されている（クロスプラットフォーム対応）
- キャッシュファイルは`./node_modules/.cache/prettier/.prettier-cache`に保存
- `--cache-strategy`のデフォルトは`content`

---

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

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

### 推奨読解順序

#### Step 1: ドキュメントコンテンツを理解する

本画面のコンテンツはMarkdownファイルで管理されています。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | cli.md | `docs/cli.md` | CLIオプション全体像を理解 |

**読解のコツ**: 各オプションはセクション（`##`）で分割されており、アンカーリンクでジャンプ可能です。

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

CLI処理の起点を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.js | `src/cli/index.js` | run関数とmain関数の処理フロー |

**主要処理フロー**:
1. **13-37行目**: run関数でコマンドライン引数をパース
2. **39-118行目**: main関数で各オプションの分岐処理
3. **69-72行目**: --version処理
4. **74-81行目**: --help処理
5. **83-85行目**: --support-info処理
6. **87-90行目**: --find-config-path処理
7. **92-95行目**: --file-info処理
8. **102-108行目**: stdin処理
9. **111-114行目**: ファイルフォーマット処理

#### Step 3: オプションパース処理を理解する

CLIオプションのパース処理を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | parse-cli-arguments.js | `src/cli/options/parse-cli-arguments.js` | 引数パース処理 |
| 3-2 | cli-options.evaluate.js | `src/cli/cli-options.evaluate.js` | CLIオプション定義 |

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

実際のフォーマット処理を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | format.js | `src/cli/format.js` | formatFiles, formatStdin関数 |
| 4-2 | format-results-cache.js | `src/cli/format-results-cache.js` | キャッシュ処理 |

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

```
prettier [options] [files]
    │
    ├─ src/cli/index.js: run()
    │      │
    │      ├─ parseArgvWithoutPlugins() - 引数パース
    │      │
    │      └─ main()
    │             │
    │             ├─ --version → printToScreen(version)
    │             ├─ --help → createUsage()
    │             ├─ --support-info → printSupportInfo()
    │             ├─ --find-config-path → logResolvedConfigPathOrDie()
    │             ├─ --file-info → logFileInfoOrDie()
    │             ├─ stdin → formatStdin()
    │             └─ files → formatFiles()
    │                           │
    │                           ├─ expandPatterns() - ファイル展開
    │                           ├─ format() - 各ファイルをフォーマット
    │                           └─ cache処理
    │
    └─ src/main/core.js: formatWithCursor()
           └─ フォーマット実行
```

### データフロー図

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

コマンドライン引数
     │
     ▼
parse-cli-arguments ────────▶ context.argv
     │
     ▼
ファイルパターン ───────────▶ expand-patterns ───────────▶ ファイルリスト
     │                                                        │
     │                                                        ▼
     │                         format.js ◀─────────────────────┘
     │                              │
     │                              ▼
     └────────────────────▶ formatWithCursor()
                                   │
                                   ▼
                            --write: ファイル上書き
                            --check: 差分判定 → exit code
                            stdout: 標準出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| cli.md | `docs/cli.md` | ドキュメント | CLIガイド |
| index.js | `src/cli/index.js` | ソース | CLIエントリーポイント |
| format.js | `src/cli/format.js` | ソース | フォーマット処理 |
| parse-cli-arguments.js | `src/cli/options/parse-cli-arguments.js` | ソース | 引数パース |
| cli-options.evaluate.js | `src/cli/cli-options.evaluate.js` | ソース | CLIオプション定義 |
| format-results-cache.js | `src/cli/format-results-cache.js` | ソース | キャッシュ処理 |
| expand-patterns.js | `src/cli/expand-patterns.js` | ソース | ファイルパターン展開 |
| usage.js | `src/cli/usage.js` | ソース | ヘルプ生成 |
| context.js | `src/cli/context.js` | ソース | コンテキスト管理 |
