# 非機能要件定義書

## 概要

本ドキュメントは、Prettierプロジェクト（コードフォーマッター）の非機能要件を定義したものです。Prettierはソースコードを一貫したスタイルでフォーマットするためのツールであり、CLI、API、ブラウザ環境での使用をサポートしています。

## 性能要件

### レスポンスタイム

| 処理種別 | 目標値 | 備考 |
| --- | --- | --- |
| フォーマット処理（単一ファイル） | ファイルサイズに依存 | `--debug-benchmark` オプションで計測可能 |
| フォーマット処理（繰り返し測定） | 平均処理時間を計測可能 | `--debug-repeat N` オプションで N 回繰り返し実行し平均を算出 |
| AST差分比較 | 2MB以下のASTを対象 | 2MBを超えるAST差分は "AST diff too large to render" として省略 |

### スループット

| 項目 | 目標値 | 備考 |
| --- | --- | --- |
| 並行ファイル処理 | 非同期処理による最適化 | `fast-glob` を使用したファイルパターン展開 |
| キャッシュによる高速化 | 変更のないファイルをスキップ | `--cache` オプションで有効化 |
| キャッシュ戦略 | metadata または content | `--cache-strategy` で選択可能 |

## 可用性要件

| 項目 | 目標値 | 備考 |
| --- | --- | --- |
| 稼働率 | CLI/APIツールとして高可用性 | オフライン動作、外部サービス依存なし |
| 計画停止時間 | なし | スタンドアロンツールのため |
| 障害復旧時間（RTO） | 即時 | 再実行により復旧 |
| 目標復旧時点（RPO） | 該当なし | 状態を持たないツール |

## セキュリティ要件

### コード品質・脆弱性対策

- **CodeQL分析**: GitHub Actions で CodeQL による静的コード解析を実施
  - 対象ブランチ: main, next, v*, patch-release
  - プルリクエスト時に自動実行
  - 設定ファイル: `.github/codeql/codeql-config.yml`

### 権限管理

- **GitHub Actions権限**:
  - `actions: read` - アクション読み取り
  - `contents: read` - コンテンツ読み取り
  - `security-events: write` - セキュリティイベント書き込み

### 入力検証

- **設定ファイル検証**: 設定ファイルのパース時にエラーハンドリング
  - `ConfigError`: 設定エラー
  - `UndefinedParserError`: 未定義パーサーエラー
- **パスの正規化**: ファイルパスは `path.resolve()` で絶対パスに正規化

## 拡張性要件

### プラグインシステム

- **ビルトインプラグイン**: 各言語用のパーサー/プリンターをプラグインとして提供
  - JavaScript (babel, acorn, espree, meriyah, oxc)
  - TypeScript
  - Flow
  - HTML
  - CSS/SCSS/Less
  - Markdown
  - YAML
  - JSON
  - GraphQL
  - Angular
  - Glimmer (Ember)

- **外部プラグイン**: カスタムプラグインの読み込みをサポート
  - `loadPlugins()` 関数で動的読み込み
  - `loadBuiltinPlugins()` でビルトインプラグインを非同期読み込み
  - プラグインキャッシュ機能あり (`clearCache()` でクリア可能)

### 設定の拡張

- **設定ファイル形式**: 複数の設定ファイル形式をサポート
  - `.prettierrc` (JSON/YAML)
  - `.prettierrc.json`, `.prettierrc.yml`, `.prettierrc.yaml`
  - `.prettierrc.js`, `.prettierrc.cjs`, `.prettierrc.mjs`
  - `.prettierrc.ts`
  - `prettier.config.js`, `prettier.config.cjs`, `prettier.config.mjs`, `prettier.config.ts`
  - `package.json` 内の `prettier` フィールド

- **EditorConfig統合**: `.editorconfig` ファイルからの設定読み込みをサポート
  - `--editorconfig` / `--no-editorconfig` オプションで制御

- **オーバーライド機能**: ファイルパターンごとの設定オーバーライド
  - `overrides` 配列で glob パターンによる設定上書き

## 保守性要件

### コード品質

- **TypeScript型チェック**: `tsc --noEmit` による型チェック
  - JSDoc によるJavaScriptファイルの型注釈
  - `tsconfig.json` で設定管理

- **ESLint**: コードスタイルとベストプラクティスの強制
  - `eslint.config.js` で設定
  - 多数のプラグイン使用 (unicorn, regexp, jest, n, compat, simple-import-sort)

- **Prettier自体によるフォーマット**: `prettier.config.js` で自己フォーマット

- **Spell Check**: `cspell` による綴りチェック

### テスト

- **テストフレームワーク**: Jest
  - `jest-light-runner` によるパフォーマンス最適化
  - スナップショットテスト
  - フォーマットテスト
  - 統合テスト
  - ユニットテスト
  - DTS (Declaration Type) テスト

- **テスト環境**:
  - Node.js: v14, v16, v18, v20, v22, v24, v25
  - OS: Ubuntu, macOS, Windows
  - ブラウザ: Chrome, Firefox

- **CI/CDタイムアウト**: テストジョブは15分でタイムアウト

### 依存関係管理

- **パッケージマネージャー**: Yarn v4
- **Knip**: 未使用の依存関係・エクスポートの検出

## 運用・監視要件

### ログ管理

- **ログレベル**: 4段階のログレベルをサポート
  - `silent`: ログ出力なし
  - `error`: エラーのみ
  - `warn`: 警告以上
  - `log`: 通常ログ以上
  - `debug`: デバッグ情報含む全て

- **色付きログ出力**:
  - 標準エラー出力への色付きログ対応
  - `NO_COLOR` / `FORCE_COLOR` 環境変数対応
  - `--color` / `--no-color` オプション対応

### キャッシュ管理

- **フォーマット結果キャッシュ**:
  - デフォルトパス: `./node_modules/.cache/prettier/.prettier-cache`
  - `--cache-location` で場所をカスタマイズ可能
  - キャッシュ戦略:
    - `metadata`: ファイルのメタデータ（タイムスタンプ）を使用
    - `content`: ファイルの内容ハッシュを使用

- **設定キャッシュ**:
  - Prettier設定のキャッシュ
  - EditorConfig設定のキャッシュ
  - `useCache` オプションで制御

### デバッグ・診断

- **ベンチマーク機能**:
  - `--debug-benchmark`: tinybench を使用した統計的に有意な測定
  - `--debug-repeat N`: N回繰り返し実行による平均測定
  - `PRETTIER_PERF_REPEAT` 環境変数でも設定可能

- **デバッグ出力**:
  - `--debug-print-ast`: ASTを出力
  - `--debug-print-doc`: ドキュメントIRを出力
  - `--debug-print-comments`: コメント情報を出力
  - `--debug-check`: フォーマットの整合性チェック

### 互換性要件

- **Node.jsバージョン**: 20以上（package.json の engines フィールド）
  - 本番テストは v14 から実行
  - v0.10.48 では適切なエラーメッセージを表示

- **ブラウザサポート**:
  - browserslist: `>0.5%, not dead, not op_mini all`
  - ESM および UMD バンドル形式

## 備考

- Prettierはオフラインで動作するCLI/ライブラリツールのため、ネットワーク関連の非機能要件（レートリミット、API応答時間など）は該当しません
- リトライ設定は外部サービス依存がないため該当しません
- 稼働率・計画停止時間などはサーバーサイドアプリケーションではないため、従来の定義は適用されません
