# 非機能要件定義書

## 概要

本ドキュメントは、Vue.js 3.5.27 コアフレームワーク（vuejs/core）のソースコードから抽出した非機能要件を定義するものである。Vue.js はクライアントサイド JavaScript フレームワークであり、コンパイラ（compiler-core, compiler-dom, compiler-sfc, compiler-ssr）、ランタイム（runtime-core, runtime-dom）、リアクティビティシステム（reactivity）、サーバーサイドレンダリング（server-renderer）等の複数パッケージで構成されるモノレポ構成をとる。本書では、コードから読み取れる性能、可用性、セキュリティ、拡張性、保守性、運用・監視に関する要件を整理する。

## 性能要件

### レスポンスタイム

| 処理種別 | 目標値 | 備考 |
| --- | --- | --- |
| 非同期コンポーネント遅延表示 | delay デフォルト 200ms | `defineAsyncComponent` の `delay` オプション。ローディングコンポーネント表示までの遅延。(`packages/runtime-core/src/apiAsyncComponent.ts`) |
| 非同期コンポーネントタイムアウト | デフォルト無制限（undefined） | `defineAsyncComponent` の `timeout` オプション。指定時間経過後にエラーコンポーネントへ切り替え。(`packages/runtime-core/src/apiAsyncComponent.ts`) |
| Idle時ハイドレーション | デフォルト 10,000ms タイムアウト | `hydrateOnIdle` 戦略の `requestIdleCallback` タイムアウト値。(`packages/runtime-core/src/hydrationStrategies.ts`) |
| DevTools バッファクリア | 3,000ms | DevTools未インストール時、メモリリーク防止のためバッファを3秒後にクリア。(`packages/runtime-core/src/devtools.ts`) |
| イベントタイムスタンプキャッシュ | 同一 tick 内で共有 | `Date.now()` の呼び出しオーバーヘッド軽減のため、同一 tick 内で `cachedNow` を共有。(`packages/runtime-dom/src/modules/events.ts`) |

### スループット

| 項目 | 目標値 | 備考 |
| --- | --- | --- |
| スケジューラ再帰制限 | 最大 100 回 | `RECURSION_LIMIT = 100`。同一ジョブの再帰的更新を検知し、無限ループを防止。(`packages/runtime-core/src/scheduler.ts`) |
| SFC パースキャッシュ | LRU 最大 500 エントリ | `createCache(max = 500)` による LRU キャッシュ。コンパイラ SFC のパース結果をキャッシュ。(`packages/compiler-sfc/src/cache.ts`) |
| KeepAlive キャッシュ | `max` プロパティで上限設定可能 | KeepAlive コンポーネントの `max` プロパティにより、キャッシュするコンポーネント数の上限を制御。超過時は最古のエントリを削除（LRU方式）。(`packages/runtime-core/src/components/KeepAlive.ts`) |
| 静的ノード文字列化閾値 | バインディング付き要素 5 個以上、ノード 20 個以上 | `StringifyThresholds` で定義。条件を満たす静的サブツリーを文字列化し、VNode 生成コストを削減。(`packages/compiler-dom/src/transforms/stringifyStatic.ts`) |

### キャッシュ設定

| キャッシュ種別 | 実装方式 | 最大サイズ | 対象 |
| --- | --- | --- | --- |
| SFC パースキャッシュ | LRU Cache（lru-cache ライブラリ） | 500 エントリ | SFC ファイルのパース結果 (`packages/compiler-sfc/src/cache.ts`) |
| コンポーネントオプションキャッシュ | WeakMap | 制限なし（GC 依存） | マージ済みコンポーネントオプション (`packages/runtime-core/src/apiCreateApp.ts`) |
| Props キャッシュ | WeakMap | 制限なし（GC 依存） | 正規化済み Props オプション (`packages/runtime-core/src/apiCreateApp.ts`) |
| Emits キャッシュ | WeakMap | 制限なし（GC 依存） | 正規化済み Emits オプション (`packages/runtime-core/src/apiCreateApp.ts`) |
| リアクティブオブジェクトマップ | WeakMap | 制限なし（GC 依存） | reactive/readonly/shallowReactive/shallowReadonly のプロキシマップ (`packages/reactivity/src/reactive.ts`) |
| KeepAlive コンポーネントキャッシュ | Map + Set（LRU 方式） | `max` プロパティで設定可能 | 非アクティブ化されたコンポーネントの VNode (`packages/runtime-core/src/components/KeepAlive.ts`) |
| 静的コンテンツキャッシュ | DOM ノード再利用 | 制限なし | `insertStaticContent` での cloneNode による再利用 (`packages/runtime-dom/src/nodeOps.ts`) |

## 可用性要件

| 項目 | 目標値 | 備考 |
| --- | --- | --- |
| エラー回復（本番環境） | エラー発生時もアプリケーション動作を継続 | 本番環境では `console.error` で記録し、クラッシュを回避する設計。`throwUnhandledErrorInProduction` オプションで挙動変更可能。(`packages/runtime-core/src/errorHandling.ts`) |
| エラー回復（開発環境） | エラーをスローし開発者に通知 | 開発環境では視認性のため `throw` する。(`packages/runtime-core/src/errorHandling.ts`) |
| 非同期コンポーネントリトライ | ユーザー定義の `onError` コールバックでリトライ可能 | `defineAsyncComponent` の `onError(error, retry, fail, attempts)` により、リトライ回数を含む制御をユーザーに委譲。(`packages/runtime-core/src/apiAsyncComponent.ts`) |
| エラー境界（errorCaptured） | コンポーネントツリーを遡るエラー伝播 | `errorCaptured` ライフサイクルフックにより、親コンポーネントでエラーをキャッチ可能。`false` を返すことでエラー伝播を停止。(`packages/runtime-core/src/errorHandling.ts`) |
| アプリケーションレベルエラーハンドラ | `app.config.errorHandler` でグローバルハンドリング | 全てのコンポーネントエラーを一元的に処理可能。(`packages/runtime-core/src/apiCreateApp.ts`) |
| スケジューラ再帰更新検出 | 100 回超過でエラー報告 | 無限ループ状態を検出し、エラーメッセージで原因コンポーネントを通知。(`packages/runtime-core/src/scheduler.ts`) |
| Suspense によるフォールバック | 非同期依存解決までフォールバック表示 | `timeout` プロパティによりフォールバック表示のタイミングを制御可能。(`packages/runtime-core/src/components/Suspense.ts`) |

## セキュリティ要件

### XSS 対策

- **HTML エスケープ**: `escapeHtml` 関数により、`"`, `&`, `'`, `<`, `>` の5文字を HTML エンティティに変換。SSR 時のテンプレート補間（`ssrInterpolate`）で自動適用される。(`packages/shared/src/escapeHtml.ts`, `packages/server-renderer/src/helpers/ssrInterpolate.ts`)
- **HTML コメントエスケープ**: `escapeHtmlComment` 関数により、コメント内の危険なパターン（`-->`, `<!--`, `--!>` 等）を除去。(`packages/shared/src/escapeHtml.ts`)
- **CSS 変数名エスケープ**: `getEscapedCssVarName` 関数により、CSS 変数名に含まれる特殊文字をエスケープ。(`packages/shared/src/escapeHtml.ts`)
- **イベントハンドラバリデーション**: `sanitizeEventValue` 関数により、イベントハンドラとして不正な値（関数・配列以外）が渡された場合に警告を出力し、NOOP に置換。(`packages/runtime-dom/src/modules/events.ts`)

### Trusted Types 対応

- **Trusted Types ポリシー**: `trustedTypes.createPolicy('vue', ...)` により、CSP の Trusted Types ディレクティブに準拠した HTML 操作を実現。`innerHTML` 設定時に `unsafeToTrustedHTML` を経由する。(`packages/runtime-dom/src/nodeOps.ts`)
- **重複ポリシー対策**: `createPolicy` が TypeError をスローする場合（CSP で `allow-duplicates` が無い場合）をキャッチし、安全にフォールバック。(`packages/runtime-dom/src/nodeOps.ts`)

### テンプレートコンパイルセキュリティ

- **静的コンテンツの制限**: `insertStaticContent` で使用される `innerHTML` は、コンパイル済みテンプレートからの静的コンテンツにのみ適用される設計。信頼されたテンプレートソースのみを前提としている。(`packages/runtime-dom/src/nodeOps.ts`)
- **ユーザー入力のテンプレート使用に対する警告**: XSS はテンプレート式経由では有効な攻撃ベクターとみなされない旨をセキュリティポリシーで明示。(`SECURITY.md`)

### 脆弱性報告

- セキュリティ脆弱性は `security@vuejs.org` へのメール報告フローが確立されている。(`SECURITY.md`)

## 拡張性要件

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

- **`app.use()` によるプラグイン登録**: `install` メソッドを持つオブジェクト、またはインストール関数を受け入れる。`WeakSet` による重複登録防止機構を備える。(`packages/runtime-core/src/apiCreateApp.ts`)
- **プラグインクリーンアップ**: `app.onUnmount()` によりプラグインのクリーンアップ処理を登録可能。アンマウント時に自動実行される。(`packages/runtime-core/src/apiCreateApp.ts`)

### コンポーネントシステム

- **グローバルコンポーネント/ディレクティブ登録**: `app.component()`, `app.directive()` による登録と重複チェック。(`packages/runtime-core/src/apiCreateApp.ts`)
- **Mixin サポート**: `app.mixin()` によるグローバルミックスイン。Options API ビルドでのみ有効。(`packages/runtime-core/src/apiCreateApp.ts`)
- **非同期コンポーネント**: `defineAsyncComponent` による遅延読み込み、ローディング/エラーコンポーネント、リトライ、タイムアウト対応。(`packages/runtime-core/src/apiAsyncComponent.ts`)
- **KeepAlive**: `include`/`exclude`/`max` プロパティによるコンポーネントキャッシュの柔軟な制御。(`packages/runtime-core/src/components/KeepAlive.ts`)

### 遅延ハイドレーション戦略

- **`hydrateOnIdle`**: `requestIdleCallback` を利用したアイドル時ハイドレーション。(`packages/runtime-core/src/hydrationStrategies.ts`)
- **`hydrateOnVisible`**: `IntersectionObserver` を利用したビューポート表示時ハイドレーション。(`packages/runtime-core/src/hydrationStrategies.ts`)
- **`hydrateOnMediaQuery`**: `matchMedia` を利用したメディアクエリ一致時ハイドレーション。(`packages/runtime-core/src/hydrationStrategies.ts`)
- **`hydrateOnInteraction`**: ユーザーインタラクション（クリック等）時ハイドレーション。イベントリプレイ機能付き。(`packages/runtime-core/src/hydrationStrategies.ts`)

### ビルド形式

- **複数出力フォーマット対応**: ESM Bundler, ESM Browser, CJS, Global (IIFE), Runtime-only の各形式をサポート。用途に応じて最適なビルドを選択可能。(`rollup.config.js`)
- **Feature Flag による条件付きコンパイル**: `__DEV__`, `__SSR__`, `__BROWSER__`, `__FEATURE_OPTIONS_API__`, `__FEATURE_SUSPENSE__`, `__FEATURE_PROD_DEVTOOLS__` 等のフラグにより、不要コードの Tree-shaking を実現。(`vitest.config.ts`, `rollup.config.js`)

## 保守性要件

### コード品質

- **TypeScript Strict モード**: `tsconfig.json` で `strict: true` を設定。型安全性を最大限に担保。(`tsconfig.json`)
- **Isolated Declarations**: `isolatedDeclarations: true` により、各ファイルの型宣言が独立して解決可能。(`tsconfig.json`)
- **未使用変数検出**: `noUnusedLocals: true` により、未使用のローカル変数を検出。(`tsconfig.json`)
- **ESLint + Prettier**: `eslint` による静的解析と `prettier` による自動フォーマット。キャッシュ機構付き。(`package.json`)
- **Pre-commit フック**: `simple-git-hooks` による pre-commit（lint-staged + 型チェック）および commit-msg フック。(`package.json`)

### テスト

- **ユニットテスト**: Vitest による複数プロジェクト構成（unit, unit-jsdom, e2e）。スレッドプールで並列実行。(`vitest.config.ts`)
- **カバレッジ**: V8 プロバイダーによるコードカバレッジ計測。`packages/*/src/**` を対象とし、テスト不能ファイルを除外。(`vitest.config.ts`)
- **E2E テスト**: Puppeteer を利用したブラウザ E2E テスト。CI 環境ではシングルスレッドで実行。(`vitest.config.ts`)
- **型テスト**: `tsc` による型テスト（`test-dts`）で型定義の正確性を検証。(`package.json`)
- **ガベージコレクションテスト**: `WeakRef` / `FinalizationRegistry` を活用したメモリリーク検証テスト。(`packages/reactivity/__tests__/gc.spec.ts`)
- **ベンチマーク**: Vitest bench による性能ベンチマーク。JSON 出力と比較機能付き。(`package.json`)

### モノレポ構成

- **pnpm ワークスペース**: `pnpm-workspace.yaml` による依存関係管理。`packages` と `packages-private` の分離。(`pnpm-workspace.yaml`)
- **パッケージ分離**: compiler-core, compiler-dom, compiler-sfc, compiler-ssr, reactivity, runtime-core, runtime-dom, runtime-test, server-renderer, shared, vue, vue-compat の12パッケージ構成。

### Tree-shaking 対応

- **`/*@__PURE__*/` アノテーション**: 副作用のない関数呼び出しに `/*@__PURE__*/` を付与し、バンドラによる Tree-shaking を促進。(`packages/runtime-core/src/devtools.ts` 他多数)
- **`/*@__NO_SIDE_EFFECTS__*/` アノテーション**: 関数定義に付与し、呼び出し元が未使用の場合に関数ごと除去可能に。(`packages/runtime-core/src/apiAsyncComponent.ts` 他)
- **Feature Flag によるデッドコード除去**: `__DEV__`, `__SSR__` 等の条件分岐により、本番ビルドから開発用コードを除去。

## 運用・監視要件

### ログ・警告

| 種別 | 環境 | 出力先 | 備考 |
| --- | --- | --- | --- |
| 警告（warn） | 開発環境のみ | `console.warn` | コンポーネントトレース付き。`app.config.warnHandler` でカスタマイズ可能。再帰呼び出し防止機構付き。(`packages/runtime-core/src/warning.ts`) |
| エラー（logError） | 開発環境 | `throw` + `console.error` | 開発環境ではスローし、テスト環境では `console.error`。(`packages/runtime-core/src/errorHandling.ts`) |
| エラー（logError） | 本番環境 | `console.error` | `throwUnhandledErrorInProduction: true` でスロー動作に変更可能（SSR等で推奨）。(`packages/runtime-core/src/errorHandling.ts`) |
| カスタム警告ハンドラ | 全環境 | `app.config.warnHandler` | `(msg, instance, trace)` の引数で警告内容、インスタンス、コンポーネントトレースを受け取る。(`packages/runtime-core/src/apiCreateApp.ts`) |
| カスタムエラーハンドラ | 全環境 | `app.config.errorHandler` | `(err, instance, info)` の引数でエラー、インスタンス、エラー種別情報を受け取る。(`packages/runtime-core/src/apiCreateApp.ts`) |

### パフォーマンスモニタリング

- **Performance API 連携**: `app.config.performance = true` により、`window.performance.mark` / `measure` を使用したコンポーネントレベルのパフォーマンス計測を有効化。初期化（init）、レンダリング（render）、パッチ（patch）のタイミングを計測。(`packages/runtime-core/src/profiling.ts`)
- **DevTools 連携**: Vue DevTools との統合により、コンポーネントツリーの可視化、イベント追跡、パフォーマンスタイムライン表示をサポート。`__FEATURE_PROD_DEVTOOLS__` フラグにより本番ビルドでも有効化可能。(`packages/runtime-core/src/devtools.ts`)

### DevTools イベント

| イベント | 説明 |
| --- | --- |
| `app:init` | アプリケーション初期化 |
| `app:unmount` | アプリケーションアンマウント |
| `component:added` | コンポーネント追加 |
| `component:updated` | コンポーネント更新 |
| `component:removed` | コンポーネント削除 |
| `component:emit` | カスタムイベント発火 |
| `perf:start` | パフォーマンス計測開始 |
| `perf:end` | パフォーマンス計測終了 |

### デバッグ機能

- **リアクティビティデバッグ**: `onTrack` / `onTrigger` コールバックにより、依存関係の追跡・トリガーをデバッグ可能。(`packages/reactivity/src/effect.ts`)
- **コンポーネントトレース**: 警告・エラー発生時にコンポーネントの親子階層をトレース表示。再帰呼び出しの回数も表示。(`packages/runtime-core/src/warning.ts`)
- **HMR（Hot Module Replacement）**: 開発環境でのコンポーネントホットリロードに対応。(`packages/runtime-core/src/hmr.ts`)

## 備考

- 本プロジェクトは Vue.js フレームワークのコアライブラリであり、サーバーアプリケーションではなくクライアントサイド JavaScript フレームワークである。そのため、一般的なサーバーサイドアプリケーションにおける稼働率、計画停止時間、障害復旧時間（RTO）、目標復旧時点（RPO）等の可用性指標は直接的には適用されない。
- レートリミット設定はコードベース内に存在しない。これはフレームワークの特性上、HTTP リクエストのレートリミットはアプリケーション層またはインフラ層の責務であるためと考えられる。
- Node.js >= 18.12.0 が動作要件として `engines` フィールドに明記されている。(`package.json`)
- MITライセンスの下で提供されている。(`LICENSE`)
