# 通知設計書 25-ファイル依存関係通知

## 概要

本ドキュメントは、Tailwind CSSのPostCSSプラグイン処理において、ファイル依存関係をPostCSSメッセージとして通知し、ビルドツール（Vite、webpack、Parcelなど）によるファイル変更時の再ビルドを可能にする通知の設計を定義する。

### 本通知の処理概要

PostCSSプラグイン（`@tailwindcss/postcss`）の処理中に、CSS生成に関与するファイル（設定ファイル、テンプレートファイルなど）をPostCSSの`result.messages`配列に`type: 'dependency'`メッセージとして追加する通知処理である。2つの異なるコンテキスト（fullRebuildPaths登録とスキャナーファイル登録）で同じメッセージ形式が使用される。

**業務上の目的・背景**：Tailwind CSSはCSS生成時にテンプレートファイル、設定ファイル、JavaScriptプラグインなど複数のファイルを参照する。これらのファイルが変更された際にCSS出力を再生成する必要がある。PostCSSの`result.messages`に依存関係を登録することで、Viteやwebpackなどのビルドツールがファイル変更を監視し、適切なタイミングで再ビルドをトリガーできるようになる。

**通知の送信タイミング**：PostCSSプラグインの`Once`フック内で、(1) コンパイラ生成時に収集された`fullRebuildPaths`（設定ファイル等）の登録時（168-173行目）、(2) スキャナーが検出したテンプレートファイルの登録時（248-253行目）の2箇所で発生する。

**通知の受信者**：PostCSSを実行するビルドツール（Vite、webpack、Parcel、Next.js等）。ビルドツールはこのメッセージを読み取り、該当ファイルのウォッチ対象への追加を行う。

**通知内容の概要**：`{ type: 'dependency', plugin: '@tailwindcss/postcss', file: '{絶対パス}', parent: '{入力CSSファイルパス}' }`の形式でPostCSSメッセージに追加される。

**期待されるアクション**：ビルドツールが依存ファイルの変更を検知した際に、該当するCSSファイルの再ビルドを自動的にトリガーする。開発者の手動操作は不要。

## 通知種別

PostCSSメッセージ（`result.messages.push`）。ビルドツールのPostCSSランナーが内部的に処理する。コンソールには直接出力されない。

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（PostCSS result.messagesへのpush） |
| 優先度 | 中（ビルド正常フロー内の処理） |
| リトライ | 無（即時追加） |

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

以下の2つの経路でファイルが収集される：

1. **fullRebuildPaths経由**（168-173行目）：`compileAst`関数の`onDependency`コールバックで収集されたファイル（JS設定ファイル、プラグインファイル等）
2. **スキャナーファイル経由**（248-253行目）：`Scanner.scan()`で検出されたテンプレートファイル。ただし入力CSSファイル自身は除外される（244-247行目）

## 通知テンプレート

### メール通知の場合

本通知はメール送信ではなく、PostCSSメッセージ追加である。

| 項目 | 内容 |
|-----|------|
| 送信元アドレス | N/A |
| 送信元名称 | N/A |
| 件名 | N/A |
| 形式 | PostCSSメッセージオブジェクト |

### 本文テンプレート

```json
{
  "type": "dependency",
  "plugin": "@tailwindcss/postcss",
  "file": "{path.resolve(file)}",
  "parent": "{result.opts.from}"
}
```

### 添付ファイル

| ファイル名 | 形式 | 条件 | 説明 |
|----------|------|------|------|
| N/A | N/A | N/A | 添付ファイルなし |

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| type | メッセージの種別 | 固定値 `'dependency'` | Yes |
| plugin | プラグイン名 | 固定値 `'@tailwindcss/postcss'` | Yes |
| file | 依存ファイルの絶対パス | `path.resolve(file)` で解決された絶対パス | Yes |
| parent | 親ファイル（入力CSSファイル）のパス | `result.opts.from` | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| ビルド処理 | fullRebuildPaths登録（168-173行目） | `context.fullRebuildPaths`が空でない場合 | JS設定/プラグインファイルの依存関係登録 |
| ビルド処理 | スキャナーファイル登録（248-253行目） | `compiler.features & Features.Utilities`がtruthy、かつファイルが入力CSSファイルと異なる場合 | テンプレートファイルの依存関係登録 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| Features.Utilitiesが無効 | Utilitiesフィーチャーが無効な場合、スキャナー経由の依存関係は登録されない |
| 入力CSSファイル自身 | スキャナー経由では、絶対パスが入力CSSファイルと一致する場合は除外される（246-247行目） |
| Features.Noneの場合 | コンパイラのfeaturesがNoneの場合はearly returnする（158-160行目） |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A["PostCSS Onceフック開始"] --> B["コンパイラ生成/取得"]
    B --> C["fullRebuildPaths登録"]
    C --> D{"各fileについて"}
    D --> E["result.messages.push(dependency)"]
    E --> F["ファイル変更時刻チェック"]
    F --> G["スキャナー設定"]
    G --> H["候補スキャン"]
    H --> I{"Features.Utilities有効?"}
    I -->|"No"| J["スキップ"]
    I -->|"Yes"| K["スキャナーファイルの依存関係登録"]
    K --> L{"各fileについて"}
    L --> M{"入力CSSと同一?"}
    M -->|"Yes"| N["スキップ"]
    M -->|"No"| O["result.messages.push(dependency)"]
    O --> P["CSS生成・最適化"]
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| N/A | N/A | データベースは使用しない |

### テーブル別参照項目詳細

本通知ではデータベースを参照しない。`context.fullRebuildPaths`（`string[]`）および`context.scanner.files`（`string[]`）を使用する。

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| N/A | N/A | データベース更新なし |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 特定のエラーケースなし | 依存関係登録自体はエラーにならない | N/A |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | N/A（エラーなし） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | 制限なし（プロジェクト内の全依存ファイルが登録される） |
| 1日あたり上限 | 制限なし |

### 配信時間帯

制限なし。PostCSSプラグイン処理時に即座に実行される。

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

ファイルの絶対パスがPostCSSメッセージに含まれる。これはビルドプロセス内部でのみ使用されるため、外部への情報漏洩リスクは低い。ただし、ビルドログに出力される場合はファイルパスが表示される可能性がある。

## 備考

- PostCSSの`result.messages`はPostCSSのプラグイン間通信およびビルドツール連携のための標準メカニズムである。
- `type: 'dependency'`はPostCSSの標準メッセージ型であり、多くのビルドツールがこの型をサポートしている。
- fullRebuildPathsは`compileAst`の`onDependency`コールバック（141行目）で収集される。
- スキャナーファイル登録時に`path.resolve(base, inputFile)`でinputFileを解決し、自己参照を排除している（241行目）。

---

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

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

### 推奨読解順序

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

PostCSSメッセージの構造と、依存関係を管理するCacheEntry構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts (postcss) | `packages/@tailwindcss-postcss/src/index.ts` | 21-29行目のCacheEntry型定義。`fullRebuildPaths: string[]`がJS設定ファイル等の依存パスを管理する |

**読解のコツ**: PostCSSメッセージは`{ type, plugin, file, parent }`の形式で、ビルドツールがファイル監視に使用する標準的なインターフェースである。

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

PostCSSプラグインの`Once`フック内でのファイル依存関係登録処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts (postcss) | `packages/@tailwindcss-postcss/src/index.ts` | 86行目の`Once`フック定義。PostCSS処理のエントリーポイント |

**主要処理フロー**:
1. **86行目**: `Once(root, { result, postcss })`フック開始
2. **124-151行目**: `createCompiler`関数。`onDependency`コールバック（141行目）で依存パスを収集
3. **167-173行目**: fullRebuildPathsの依存関係メッセージ登録
4. **237-253行目**: スキャナーファイルの依存関係メッセージ登録

#### Step 3: fullRebuildPaths登録処理を理解する

コンパイラ生成時に収集された依存パスの登録処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.ts (postcss) | `packages/@tailwindcss-postcss/src/index.ts` | 167-173行目のforループ。`context.fullRebuildPaths`の各ファイルについて`result.messages.push`を実行 |

**主要処理フロー**:
- **167行目**: `for (let file of context.fullRebuildPaths)`ループ開始
- **168-173行目**: `result.messages.push({ type: 'dependency', plugin: '@tailwindcss/postcss', file: path.resolve(file), parent: result.opts.from })`

#### Step 4: スキャナーファイル登録処理を理解する

スキャナーが検出したテンプレートファイルの依存関係登録を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | index.ts (postcss) | `packages/@tailwindcss-postcss/src/index.ts` | 241-253行目。スキャナーが検出した各ファイルについて、入力CSS自身を除外しつつ依存関係を登録する |

**主要処理フロー**:
- **241行目**: `path.resolve(base, inputFile)`で入力CSSの絶対パスを取得
- **242行目**: `context.scanner.files`でスキャンされたファイル一覧を取得
- **243行目**: 各ファイルの絶対パスを`path.resolve(file)`で解決
- **245-247行目**: 入力CSSファイルと同一パスの場合はスキップ
- **248-253行目**: `result.messages.push`で依存関係を登録

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

```
tailwindcss PostCSS Plugin (index.ts:71)
    |
    +-- Once(root, {result, postcss}) (index.ts:86)
           |
           +-- createCompiler() (index.ts:124)
           |      |
           |      +-- compileAst(ast, {onDependency}) (index.ts:137-141)
           |             |
           |             +-- onDependency(path) → fullRebuildPaths.push(path) (index.ts:141)
           |
           +-- [fullRebuildPaths 依存関係登録] (index.ts:167-173)
           |      |
           |      +-- result.messages.push({type:'dependency', file, ...})
           |
           +-- Scanner.scan() (index.ts:234)
           |
           +-- [スキャナーファイル 依存関係登録] (index.ts:242-253)
                  |
                  +-- result.messages.push({type:'dependency', file, ...})
```

### データフロー図

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

compileAst                    fullRebuildPaths              result.messages[]
onDependency      ───>        依存パス収集          ───>    {type:'dependency',
(JS設定/プラグイン)                                          plugin:'@tailwindcss/postcss',
                                                            file: 絶対パス,
Scanner.scan()                scanner.files                 parent: 入力CSS}
(テンプレートファイル) ───>    ファイル一覧          ───>         ↓
                              (入力CSS除外)                  ビルドツールが
                                                            ファイル監視に利用
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts (postcss) | `packages/@tailwindcss-postcss/src/index.ts` | ソース | PostCSSプラグインのメイン処理。ファイル依存関係の登録処理（167-173行目、248-253行目） |
| ast.ts (postcss) | `packages/@tailwindcss-postcss/src/ast.ts` | ソース | PostCSS ASTとTailwind CSS AST間の変換処理 |
