# 非機能要件定義書

## 概要

本ドキュメントは、Tailwind CSS v4.2.1 プロジェクトの非機能要件を定義する。Tailwind CSS はユーティリティファーストの CSS フレームワークであり、ビルドツール（CLI / Vite プラグイン / PostCSS プラグイン）を通じて CSS を生成するツールチェインとして提供される。コアエンジンは TypeScript（CSS コンパイル・AST 処理）と Rust（ファイルスキャン・候補抽出: `@tailwindcss/oxide`）のハイブリッド構成である。本ドキュメントではコードベースから読み取れる性能・可用性・セキュリティ・拡張性・保守性・運用要件を整理する。

## 性能要件

### レスポンスタイム

| 処理種別 | 目標値 | 備考 |
| --- | --- | --- |
| CSS コンパイル（初回ビルド） | プロジェクト規模に依存（ベンチマーク測定対象） | `packages/tailwindcss/src/index.bench.ts` でベンチマーク計測。`compile` 関数の実行時間を計測対象とする |
| インクリメンタルビルド（差分検出） | 初回ビルドより大幅に短縮 | `build()` 関数内でキャッシュ機構（`compiled ??= optimizeAst(...)` パターン）により、候補に変更がない場合はキャッシュされた AST を返却し再コンパイルを回避する |
| CSS パーサー | `preflight.css` 相当のファイルをミリ秒単位で処理 | `packages/tailwindcss/src/css-parser.bench.ts` でベンチマーク計測 |
| CSS 出力（toCss） | AST からの CSS 文字列生成をミリ秒単位で処理 | `packages/tailwindcss/src/ast.bench.ts` でベンチマーク計測 |
| ファイルスキャン（Oxide） | 大規模プロジェクトでも秒単位で完了 | Rust の `rayon` による並列処理、`fast_skip` による SIMD 風ホワイトスペーススキップ最適化を実装 |

### スループット

| 項目 | 目標値 | 備考 |
| --- | --- | --- |
| ファイルスキャン並列度 | CPU コア数に応じた自動スケーリング | `rayon` クレートによる並列イテレータ（`par_iter`, `into_par_iter`）、`ignore` クレートの `WalkParallel` によるマルチスレッドファイル走査。スレッド数 0 の場合 `std::thread::available_parallelism()` で自動決定 |
| 候補抽出スループット | `throughput.rs` による計測（バイト/秒単位） | `Throughput::compute` でイテレーション数とメモリベースラインから処理速度を算出 |
| IntelliSense 応答 | クラスリスト・バリアント取得をミリ秒単位で処理 | `packages/tailwindcss/src/intellisense.bench.ts` でベンチマーク計測。`getClassList`, `getVariants`, `candidatesToCss` が対象 |

### キャッシュ設定

| キャッシュ種別 | 実装箇所 | 詳細 |
| --- | --- | --- |
| AST コンパイルキャッシュ | `packages/tailwindcss/src/index.ts` | `compiled` 変数による AST キャッシュ。候補に変更がない場合は `compiled ??= optimizeAst(ast, designSystem, opts.polyfills)` で再利用 |
| パース結果キャッシュ | `packages/tailwindcss/src/design-system.ts` | `DefaultMap` を使用した自動メモ化。`parsedVariants`, `parsedCandidates`, `compiledAstNodes` がそれぞれキャッシュ |
| 候補正規化キャッシュ | `packages/tailwindcss/src/canonicalize-candidates.ts` | 11種類のキャッシュ（`SIGNATURE_OPTIONS_KEY`, `CANONICALIZE_CANDIDATE_KEY` 等）を `designSystem.storage` に格納 |
| Arbitrary Value キャッシュ | `packages/tailwindcss/src/candidate.ts` | `printArbitraryValueCache`, `simplifyArbitraryVariantCache`, `isVarCache` を `DefaultMap` で実装 |
| ファイルシステムキャッシュ | `packages/@tailwindcss-node/src/compile.ts` | `EnhancedResolve.CachedInputFileSystem(fs, 4000)` で4秒間のファイルシステムキャッシュ（CSS / ESM / CJS リゾルバ共通） |
| mtime ベースキャッシュ | `crates/oxide/src/scanner/mod.rs` | `mtimes: FxHashMap<PathBuf, SystemTime>` でファイルの変更時刻を追跡。初回スキャン後の再スキャンで未変更ファイルをスキップ |
| 共有バッファ最適化 | `packages/tailwindcss/src/utils/segment.ts` | `closingBracketStack` を `Uint8Array(256)` の共有バッファとして確保し、関数呼び出しごとのメモリアロケーションを回避 |

### タイムアウト設定

| 設定箇所 | タイムアウト値 | 備考 |
| --- | --- | --- |
| 統合テスト（デフォルト） | `integrations/utils.ts` の `TEST_TIMEOUT` で定義 | テスト実行時のタイムアウト |
| 統合テスト（アップグレード） | 120,000ms - 180,000ms | `integrations/upgrade/index.test.ts` で個別に設定 |
| アサーションリトライ | `ASSERTION_TIMEOUT` + 5ms 遅延 | `integrations/utils.ts` の `retryAssertion` で使用 |
| 正規化テスト | 25,000ms | `canonicalize-candidates.test.ts` で設定 |

### リトライ設定

| 設定箇所 | リトライ回数 | 備考 |
| --- | --- | --- |
| 統合テスト（CI環境） | 2回 | `integrations/utils.ts` で `process.env.CI ? 2 : 0` として定義 |
| 統合テスト（ローカル） | 0回（リトライなし） | 開発環境ではリトライを行わない |
| アサーションリトライ | タイムアウトまで繰り返し | `retryAssertion` で `Date.now() + timeout` まで `delay` 間隔で再試行 |

## 可用性要件

| 項目 | 目標値 | 備考 |
| --- | --- | --- |
| 稼働率 | 該当なし（ビルドツールのため実行時サービスとしての稼働率は対象外） | Tailwind CSS はランタイムサービスではなくビルドタイムツールである |
| 計画停止時間 | 該当なし | 同上 |
| 障害復旧時間（RTO） | 該当なし | 同上 |
| 目標復旧時点（RPO） | 該当なし | 同上 |
| エラー復旧（CSS 最適化） | LightningCSS の `errorRecovery: true` によるグレースフルデグラデーション | `packages/@tailwindcss-node/src/optimize.ts` で無効な CSS 構文を検出しても処理を継続し、警告を出力 |
| モジュールインポートフォールバック | ネイティブ `import()` 失敗時に `jiti` へフォールバック | `packages/@tailwindcss-node/src/compile.ts` の `importModule` 関数で実装。TypeScript ファイルの直接インポートに対応 |
| ウォッチモードの耐障害性 | 初回スキャン後の差分検出による増分処理 | `Scanner` の `has_scanned_once` フラグにより初回/増分スキャンを切り替え。並列ウォーカーのデデュプリケーション機構あり |

## セキュリティ要件

| 項目 | 実装内容 | 備考 |
| --- | --- | --- |
| 入力バリデーション | CSS パーサーでの構文エラーハンドリング、`@source` / `@utility` / `@custom-variant` のパラメータ検証 | 各 at-rule ディレクティブで不正な入力に対し明示的なエラーメッセージを生成（例: `@source paths must be quoted.`, `@utility cannot be nested.`） |
| パスの正規化 | `dunce::canonicalize` によるパス正規化 | `crates/oxide/src/scanner/mod.rs` でファイルパスを正規化し、シンボリックリンク攻撃を防止 |
| gitignore ルールの適用 | `ignore` クレートによる `.gitignore` パターンの自動適用 | ファイルスキャン時に `.gitignore` で除外されたファイルを自動的にスキップ |
| npm パッケージの provenance | `publishConfig.provenance: true` | 全パッケージで npm provenance を有効化し、パッケージの出所を検証可能にする |
| ライセンス管理 | MIT License | プロジェクト全体が MIT License で管理される |
| CSS セレクタのエスケープ | `packages/tailwindcss/src/utils/escape.ts` | ユーザー入力由来のクラス名を CSS セレクタに変換する際にエスケープ処理を実施 |
| 環境変数経由の機能制御 | `FEATURES_ENV` による機能フラグ | `feature-flags.ts` で `process.env.FEATURES_ENV !== 'stable'` により実験的機能の有効/無効を制御。`tsup.config.ts` でビルド時に埋め込み |
| unsafe コードの制限 | Rust コード内で最小限の `unsafe` 使用 | `String::from_utf8_unchecked` は事前にバリデーション済みのバイト列にのみ適用。`get_unchecked` は境界チェック済み |

## 拡張性要件

| 項目 | 実装内容 | 備考 |
| --- | --- | --- |
| プラグインシステム | `@plugin` ディレクティブによる JavaScript プラグインの読み込み | `packages/tailwindcss/src/compat/apply-compat-hooks.ts` で後方互換性を維持しつつプラグインを適用 |
| カスタムユーティリティ | `@utility` ディレクティブによる CSS ベースのユーティリティ定義 | `packages/tailwindcss/src/index.ts` で `createCssUtility` を呼び出し、ユーザー定義ユーティリティを登録 |
| カスタムバリアント | `@custom-variant` ディレクティブによるバリアント定義 | セレクタベース・ボディベースの2パターンをサポート。`topologicalSort` による依存関係解決 |
| テーマカスタマイズ | `@theme` ディレクティブによる CSS 変数ベースのテーマ設定 | `ThemeOptions` フラグ（`REFERENCE`, `INLINE`, `DEFAULT`, `STATIC`）による柔軟な制御 |
| ソース検出拡張 | `@source` ディレクティブによるスキャン対象の追加・除外 | `not` 修飾子、`inline(...)` 修飾子、glob パターンをサポート |
| ビルドツール統合 | Vite / PostCSS / Webpack / CLI の各プラグイン | 各ビルドツール向けの専用パッケージとして提供。Vite は `vite ^5.2.0 || ^6 || ^7` をサポート |
| ブラウザ向けビルド | `@tailwindcss/browser` パッケージ | ブラウザ環境での CSS コンパイルをサポート |
| プリプロセッサ対応 | 多言語ファイルの前処理 | `pre_process_input` で Clojure / Elixir / Razor / Haml / JSON / Markdown / Pug / Ruby / Slim / Svelte / Rust / Vue に対応 |
| Polyfill 制御 | `Polyfills` enum による段階的なポリフィル適用 | `@property` ルール・`color-mix()` のフォールバックを個別に制御可能 |

## 保守性要件

| 項目 | 実装内容 | 備考 |
| --- | --- | --- |
| モノレポ構成 | pnpm workspace + Turborepo による管理 | `pnpm-workspace.yaml` でワークスペース定義、`turbo.json` でビルドパイプライン管理 |
| 型安全性 | TypeScript（strict mode）+ Rust の型システム | TypeScript 5.5.4+、Rust 1.85.0 を使用。`tsc --noEmit` による型チェック |
| テストフレームワーク | Vitest（ユニットテスト・ベンチマーク）+ Playwright（E2E テスト） | `vitest ^4.0.18`、`@playwright/test ^1.58.0` を使用 |
| コードフォーマット | Prettier による自動フォーマット | セミコロンなし、シングルクォート、100文字幅の統一ルール |
| ビルドシステム | tsup（TypeScript バンドル）+ napi-rs（Rust バイナリ） | ESM / CJS デュアルフォーマット出力、型定義ファイル自動生成 |
| LTO（Link Time Optimization） | Cargo プロファイルで `lto = true` | `Cargo.toml` の `[profile.release]` で有効化。リリースビルドの最適化 |
| ソースマップサポート | コンパイル時のソースマップ生成 | `packages/tailwindcss/src/source-maps/` で実装。`@jridgewell/remapping` による多段ソースマップ合成 |
| 後方互換性レイヤー | `packages/tailwindcss/src/compat/` | v3 からの移行パスを提供。`applyCompatibilityHooks` で旧設定・旧プラグイン API をサポート |
| 依存関係のパッチ管理 | pnpm `patchedDependencies` | `lightningcss@1.31.1` と `@parcel/watcher@2.5.1` にパッチを適用 |
| ブラウザターゲット | LightningCSS での明示的なターゲット指定 | Safari 16.4+, Firefox 128+, Chrome 111+ を対象。`optimize.ts` で設定 |

## 運用・監視要件

| 項目 | 実装内容 | 備考 |
| --- | --- | --- |
| デバッグモード（TypeScript） | `DEBUG` 環境変数による詳細ログ出力 | `packages/@tailwindcss-node/src/env.ts` で `DEBUG=tailwindcss` または `DEBUG=*` で有効化 |
| デバッグモード（Rust） | `DEBUG=tailwindcss:oxide` による Rust 側トレーシング | `crates/oxide/src/scanner/init_tracing.rs` で `tracing_subscriber` を使用。ログファイル `tailwindcss-{pid}.log` に出力 |
| インストゥルメンテーション | `Instrumentation` クラスによる計測 | `packages/@tailwindcss-node/src/instrumentation.ts` でヒット数・タイマー（ナノ秒精度: `process.hrtime.bigint()`）を計測。`Symbol.dispose` による自動レポート出力 |
| Rust トレーシング | `tracing` クレートによるスパンベースの計測 | `#[tracing::instrument(skip_all)]` アトリビュートで各メソッドの実行時間を自動計測 |
| 警告出力 | CSS 最適化時の警告表示 | `optimize.ts` で LightningCSS の警告をフィルタリングして表示。行番号・コンテキスト付きのスニペット表示 |
| バージョン管理 | ビルド出力への自動バージョン埋め込み | `compile` 関数で `tailwindcss v${version}` コメントを出力 CSS に挿入 |
| ファイルウォッチ | `@parcel/watcher`（CLI）/ Vite 内蔵ウォッチャー | CLI では `@parcel/watcher ^2.5.1` を使用。Vite プラグインでは `addWatchFile` API を活用 |
| CI 統合 | テストリトライ・タイムアウトの CI 対応 | `process.env.CI` でリトライ回数を制御（CI: 2回、ローカル: 0回） |

## 備考

- 本プロジェクトはビルドタイムツールであり、ランタイムサービスとしての可用性・稼働率は対象外である
- 性能要件の具体的な目標値はベンチマークテストファイル（`*.bench.ts`）で計測されるが、明示的な SLA は設定されていない
- Rust（`@tailwindcss/oxide`）と TypeScript の責務分離により、ファイルスキャン・候補抽出は Rust の高速処理に委譲し、CSS コンパイル・AST 操作は TypeScript で実装する二層アーキテクチャを採用している
- 機能フラグ（`FEATURES_ENV`）により、安定版とインサイダー版（実験的機能有効）を切り替え可能
