# 通知設計書 26-ディレクトリ依存関係通知

## 概要

本ドキュメントは、Tailwind CSSのPostCSSプラグイン処理において、ディレクトリ依存関係をglobパターン付きでPostCSSメッセージとして通知し、ビルドツールによるディレクトリ内ファイル変更時の再ビルドを可能にする通知の設計を定義する。

### 本通知の処理概要

PostCSSプラグイン（`@tailwindcss/postcss`）の処理中に、Scannerが管理するglob情報（ベースディレクトリとパターン）をPostCSSの`result.messages`配列に`type: 'dir-dependency'`メッセージとして追加する通知処理である。パターンが空の場合は通常の`type: 'dependency'`として登録され、パターンがある場合は`dir-dependency`型として登録される。

**業務上の目的・背景**：Tailwind CSSは`@source`ディレクティブやデフォルト設定に基づいてソースファイルをスキャンする際、globパターン（例：`**/*`）を使用する。ビルドツール（特にViteやParcel）はディレクトリ単位の依存関係をglobパターン付きで受け取ることで、不要なファイル監視を削減し、効率的な再ビルドを実現できる。例えば`**/*.{html,js,tsx}`のようなパターンを使用すると、画像ファイルなどの変更では再ビルドがトリガーされない。

**通知の送信タイミング**：PostCSSプラグインの`Once`フック内で、`compiler.features & Features.Utilities`がtruthyの場合に、`context.scanner.globs`から取得したglob情報をもとにメッセージが登録される（275-281行目）。

**通知の受信者**：PostCSSを実行するビルドツール（Vite、Parcel、Next.js等）。ビルドツールはこのメッセージを読み取り、ディレクトリ内のファイル変更監視にglobパターンを適用する。

**通知内容の概要**：パターン空の場合は`{ type: 'dependency', file: '{ディレクトリ絶対パス}', ... }`、パターンありの場合は`{ type: 'dir-dependency', dir: '{ディレクトリ絶対パス}', glob: '{パターン}', ... }`の形式で追加される。

**期待されるアクション**：ビルドツールが指定されたディレクトリ内でglobパターンにマッチするファイルの変更を監視し、変更検知時にCSSの再ビルドを自動的にトリガーする。開発者の手動操作は不要。

## 通知種別

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

## 送信仕様

### 基本情報

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

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

`context.scanner.globs`から取得したglob情報に基づき、以下の分岐で送信先メッセージ型を決定する：

1. **パターンが空文字列**の場合：`type: 'dependency'`でディレクトリ自体を依存関係として登録
2. **パターンがある**場合：`type: 'dir-dependency'`でディレクトリとglobパターンを依存関係として登録
3. **例外**：`pattern === '*' && base === globBase`の場合はスキップ（Next.jsの無限再帰を回避）

## 通知テンプレート

### メール通知の場合

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

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

### 本文テンプレート

パターン空の場合：
```json
{
  "type": "dependency",
  "plugin": "@tailwindcss/postcss",
  "file": "{path.resolve(globBase)}",
  "parent": "{result.opts.from}"
}
```

パターンありの場合：
```json
{
  "type": "dir-dependency",
  "plugin": "@tailwindcss/postcss",
  "dir": "{path.resolve(globBase)}",
  "glob": "{pattern}",
  "parent": "{result.opts.from}"
}
```

### 添付ファイル

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

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| type | メッセージ種別 | `'dependency'`または`'dir-dependency'`（パターン有無で決定） | Yes |
| plugin | プラグイン名 | 固定値 `'@tailwindcss/postcss'` | Yes |
| dir / file | ディレクトリまたはファイルの絶対パス | `path.resolve(globBase)` | Yes |
| glob | ファイルパターン | `context.scanner.globs`のpatternフィールド | dir-dependency時のみ |
| parent | 親ファイルのパス | `result.opts.from` | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| ビルド処理 | スキャナーglob情報の登録（259-283行目） | `compiler.features & Features.Utilities`がtruthy | ディレクトリ依存関係の登録 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| Features.Utilitiesが無効 | Utilitiesフィーチャーが無効な場合は登録されない |
| `pattern === '*' && base === globBase` | ベースディレクトリ自身の`*`パターンはNext.jsの無限再帰問題を回避するためスキップされる（263-264行目） |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A["PostCSS Onceフック"] --> B{"Features.Utilities有効?"}
    B -->|"No"| C["スキップ"]
    B -->|"Yes"| D["context.scanner.globsを取得"]
    D --> E{"各{globBase, pattern}について"}
    E --> F{"pattern === '*' && base === globBase?"}
    F -->|"Yes"| G["スキップ（Next.js対策）"]
    F -->|"No"| H{"pattern === '' ?"}
    H -->|"Yes"| I["type:'dependency'でディレクトリ登録"]
    H -->|"No"| J["type:'dir-dependency'でglob付き登録"]
    I --> K["result.messages.push"]
    J --> K
```

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

### 参照テーブル一覧

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

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

本通知ではデータベースを参照しない。`context.scanner.globs`（`{ base: string, pattern: string }[]`）を使用する。

### 更新テーブル一覧

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | 制限なし |
| 1日あたり上限 | 制限なし |

### 配信時間帯

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

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

ディレクトリの絶対パスとglobパターンがPostCSSメッセージに含まれる。ビルドプロセス内部でのみ使用されるため、外部への情報漏洩リスクは低い。

## 備考

- `type: 'dir-dependency'`はPostCSSの拡張メッセージ型であり、ViteやParcelなどのビルドツールがサポートしている。
- Next.jsでは`distDir`がデフォルトの`.next`以外に設定されている場合、ベースディレクトリの`*`パターンが無限再帰を引き起こすため、明示的にスキップされている（262-265行目のコメント参照）。
- glob情報は`Scanner`クラス（`@tailwindcss/oxide`パッケージ）が管理しており、`@source`ディレクティブやデフォルト設定に基づいて構成される。

---

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

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

### 推奨読解順序

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

Scannerのglobs構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts (postcss) | `packages/@tailwindcss-postcss/src/index.ts` | 259行目の`context.scanner.globs`参照。`{ base: string, pattern: string }`配列 |

**読解のコツ**: `scanner.globs`はScannerクラスが`@source`ディレクティブやデフォルト設定から構築したglobパターンの一覧を返す。各エントリは`base`（ベースディレクトリ）と`pattern`（globパターン文字列）のペアである。

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

PostCSSプラグインの依存関係登録ブロックを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts (postcss) | `packages/@tailwindcss-postcss/src/index.ts` | 259-283行目のglob登録ループ。3パターン（スキップ、dependency、dir-dependency）の分岐を理解する |

**主要処理フロー**:
1. **259行目**: `for (let { base: globBase, pattern } of context.scanner.globs)`ループ開始
2. **263-265行目**: `pattern === '*' && base === globBase`の場合はNext.js対策としてスキップ
3. **267行目**: `pattern === ''`の場合の分岐
4. **268-273行目**: パターン空の場合は`type: 'dependency'`でディレクトリ自体を登録
5. **275-281行目**: パターンありの場合は`type: 'dir-dependency'`でglob付き登録

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

```
tailwindcss PostCSS Plugin (index.ts:71)
    |
    +-- Once(root, {result, postcss}) (index.ts:86)
           |
           +-- Scanner作成/取得 (index.ts:211-231)
           |
           +-- [ディレクトリ依存関係登録] (index.ts:259-283)
                  |
                  +-- for (let {base, pattern} of scanner.globs)
                         |
                         +-- [Skip] pattern='*' && base=globBase (index.ts:263)
                         |
                         +-- pattern='' → result.messages.push({type:'dependency'}) (index.ts:268-273)
                         |
                         +-- pattern有 → result.messages.push({type:'dir-dependency'}) (index.ts:275-281)
```

### データフロー図

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

Scanner.globs                 パターン判定              result.messages[]
[{base, pattern}]  ───>       pattern分岐         ───>  {type:'dependency', file:dir}
                              |                         または
@source "**/*.tsx"            +-- '' → dependency       {type:'dir-dependency',
@source "./components"        +-- '*' && base同一 → skip  dir:dir, glob:pattern}
                              +-- other → dir-dep            ↓
                                                        ビルドツールが
                                                        ディレクトリ監視に利用
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts (postcss) | `packages/@tailwindcss-postcss/src/index.ts` | ソース | PostCSSプラグインのメイン処理。ディレクトリ依存関係の登録処理（259-283行目） |
