# 通知設計書 27-cross join用 by = character() 非推奨

## 概要

本ドキュメントは、dplyrパッケージのjoin関数において、`by = character()` を使用してcross joinを実行することが非推奨となったことに関する通知の設計書です。

### 本通知の処理概要

この通知は、`inner_join()`、`left_join()`、`right_join()`、`full_join()` などのjoin関数で `by = character()` または `by = list(x = character(), y = character())` を指定した場合に発生する非推奨警告の処理内容を定義します。

**業務上の目的・背景**：dplyr 1.1.0で専用の `cross_join()` 関数が導入されました。`by = character()` によるcross joinは、APIの明確さと意図の明示性の観点から非推奨となりました。cross joinは2つのデータフレームの全ての行の組み合わせを生成する特殊な操作であり、専用関数を使用することで意図が明確になり、誤使用のリスクが軽減されます。

**通知の送信タイミング**：join関数の実行時に、`by` 引数が空の文字ベクトル（`character()`）または同等のリスト形式で指定された場合に警告が発生します。これは `is_cross_by()` 関数で検出されます。

**通知の受信者**：dplyrパッケージを使用するRユーザー（データサイエンティスト、統計分析者、Rプログラマー）が対象です。特に、cross joinを使用している既存コードの保守者に向けた通知です。

**通知内容の概要**：警告メッセージとして「`by = character()` によるcross joinは非推奨であり、`cross_join()` を使用すべき」という内容が表示されます。

**期待されるアクション**：受信者は `by = character()` の指定を削除し、代わりに `cross_join()` 関数を使用することが期待されます。

## 通知種別

コンソール警告（lifecycle::deprecate_warn）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（関数実行時即時） |
| 優先度 | 中 |
| リトライ | 無 |

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

Rセッション内でjoin関数を呼び出し、`by` 引数が cross join を示す形式（空の文字ベクトルまたは同等のリスト）である場合にコンソールを通じて警告メッセージが表示されます。この警告は `lifecycle` パッケージの `deprecate_warn()` 関数により管理されます。

## 通知テンプレート

### コンソール警告の場合

| 項目 | 内容 |
|-----|------|
| 送信元 | dplyrパッケージ |
| 送信元名称 | lifecycle::deprecate_warn |
| 形式 | テキスト |

### 本文テンプレート

```
Using `by = character()` to perform a cross join was deprecated in dplyr 1.1.0.
i Please use `cross_join()` instead.
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| when | 非推奨となったバージョン | ハードコード値 "1.1.0" | Yes |
| what | 非推奨となった機能 | ハードコード値 "Using `by = character()` to perform a cross join" | Yes |
| with | 推奨される代替 | ハードコード値 "cross_join()" | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 関数呼び出し | join関数 | `is_cross_by(by)` が TRUE | by引数が空の文字ベクトルまたは同等のリスト |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| `by` 引数が NULL の場合 | natural joinとして処理される |
| `by` 引数が1つ以上の変数を指定する場合 | 通常のjoinとして処理される |
| `cross_join()` 関数を使用する場合 | 正常な使用方法として処理される |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[join関数呼び出し] --> B{by引数をis_cross_byでチェック}
    B -->|character()| C[is_cross_by = TRUE]
    B -->|list(x=char(),y=char())| C
    B -->|その他| D[通常処理]
    C --> E[warn_join_cross_by関数呼び出し]
    E --> F[lifecycle::deprecate_warn発行]
    F --> G[cross = TRUE設定]
    G --> H[join処理継続]
    D --> H
```

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

### 参照テーブル一覧

該当なし（インメモリ処理のみ）

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 該当なし | この通知は警告のみで、エラーは発生しない | - |

### リトライ仕様

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

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| セッションあたり | lifecycleパッケージのデフォルト動作（同一IDは1回のみ） |

### 配信時間帯

制限なし（関数呼び出し時に即時発行）

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

特になし。本通知はユーザーコンソールへの警告表示のみで、個人情報やセキュリティに関わるデータは含まれません。

## 備考

- この非推奨警告は dplyr 1.1.0 で導入されました
- `id = "dplyr-by-for-cross-join"` により警告が識別されます
- 警告発行後も、cross joinは内部的に実行され続けます（`cross = TRUE`）
- 将来のバージョンでは、`by = character()` のサポートが完全に削除される可能性があります

---

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

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

### 推奨読解順序

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

まず、`by` 引数の解析方法を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | join.R | `R/join.R` | `is_cross_by()` 関数の条件を理解する |

**読解のコツ**: `character()` と `list(x = character(), y = character())` の両形式の検出を理解することが重要です。

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

処理の起点となる関数を特定します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | join.R | `R/join.R` | `join_mutate()` 関数の定義 |
| 2-2 | join.R | `R/join.R` | `join_filter()` 関数の定義 |

**主要処理フロー**:
1. **行687-802**: `join_mutate()` 関数の完全な実装
2. **行714-720**: `is_cross_by()` チェックと `warn_join_cross_by()` 呼び出し
3. **行804-889**: `join_filter()` 関数の完全な実装
4. **行824-830**: 同様のチェックと警告

#### Step 3: cross joinの検出と警告発行を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | join.R | `R/join.R` | `is_cross_by()` 関数の実装 |
| 3-2 | join.R | `R/join.R` | `warn_join_cross_by()` 関数の実装 |

**主要処理フロー**:
- **行910-927**: `is_cross_by()` 関数の完全な実装
- **行911-913**: 空の文字ベクトルの検出
- **行916-924**: リスト形式の検出
- **行929-940**: `warn_join_cross_by()` 関数の完全な実装
- **行932-938**: `lifecycle::deprecate_warn()` 呼び出し

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

```
inner_join() / left_join() / right_join() / full_join()
    │
    └─ *.data.frame() メソッド
           │
           └─ join_mutate() / join_filter()
                  │
                  ├─ is_cross_by(by)
                  │      │
                  │      └─ character() または list(x=char(),y=char()) を検出
                  │
                  └─ warn_join_cross_by()
                         │
                         └─ lifecycle::deprecate_warn()
                                │
                                └─ 警告メッセージ発行

semi_join() / anti_join() / nest_join()
    │
    └─ 同様の処理フロー
```

### データフロー図

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

by = character() ───▶ is_cross_by() ───▶ TRUE
     │                     │                   │
     │                     └─▶ warn_join_cross_by()
     │                              │
     │                              └─▶ 警告メッセージ
     │
     └─────────────────────────────────────▶ cross join実行
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| join.R | `R/join.R` | ソース | join関数と非推奨チェックの実装 |
| lifecycle | 外部パッケージ | 依存関係 | deprecate_warn関数の提供 |
