# 通知設計書 30-across missing cols 非推奨

## 概要

本ドキュメントは、dplyrパッケージの `across()` 関数において `.cols` 引数を省略することが非推奨となったことに関する通知の設計書です。

### 本通知の処理概要

この通知は、`across()` 関数を `.cols` 引数なしで呼び出した場合に発生する非推奨警告の処理内容を定義します。

**業務上の目的・背景**：`across()` 関数は本来、変換を適用する列を `.cols` 引数で明示的に指定することを想定しています。`.cols` を省略した場合、以前は暗黙的に `everything()` が使用されていましたが、この挙動は意図しない結果を引き起こす可能性がありました。dplyr 1.1.0で、明示的な列指定を強制することで、コードの意図を明確にし、予期しない動作を防止するようになりました。

**通知の送信タイミング**：`across()` 関数を呼び出し、`.cols` 引数が省略された場合に警告が発生します。これは `across()` 関数の実行時に `quo_is_missing()` で検出されます。

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

**通知内容の概要**：警告メッセージとして「`.cols` 引数なしで `across()` を使用することは非推奨であり、`.cols` を明示的に指定すべき」という内容が表示されます。

**期待されるアクション**：受信者は `across(.fns = mean)` のような形式を `across(everything(), mean)` のように `.cols` を明示的に指定する形式に変更することが期待されます。

## 通知種別

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

## 送信仕様

### 基本情報

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

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

Rセッション内で `across()` を呼び出し、`.cols` 引数が省略された場合にコンソールを通じて警告メッセージが表示されます。この警告は `lifecycle` パッケージの `deprecate_warn()` 関数により管理され、`always = TRUE` により毎回表示されます。

## 通知テンプレート

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

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

### 本文テンプレート

```
Using `across()` without supplying `.cols` was deprecated in dplyr 1.1.0.
i Please supply `.cols` instead.
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| when | 非推奨となったバージョン | ハードコード値 "1.1.0" | Yes |
| what | 非推奨となった機能 | ハードコード値 "Using `across()` without supplying `.cols`" | Yes |
| details | 追加情報 | ハードコード値 "Please supply `.cols` instead." | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 関数呼び出し | `across(.fns = fn)` | `.cols` が省略された | `quo_is_missing(.cols)` で判定 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| `.cols` が明示的に指定された場合 | 推奨される使用方法 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[across関数呼び出し] --> B[.colsをenquoでキャプチャ]
    B --> C{quo_is_missing(.cols)?}
    C -->|Yes| D[across_missing_cols_deprecate_warn呼び出し]
    C -->|No| E[通常処理継続]
    D --> F[lifecycle::deprecate_warn発行]
    F --> G[.colsにeverything()を設定]
    G --> E
```

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

### 参照テーブル一覧

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

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| セッションあたり | 無制限（always = TRUE により毎回表示） |

### 配信時間帯

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

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

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

## 備考

- この非推奨警告は dplyr 1.1.0 で導入されました
- `id = "dplyr-across-missing-cols"` により警告が識別されます
- 警告発行後、`.cols` は暗黙的に `everything()` に設定されて処理が継続されます
- `if_any()` と `if_all()` 関数でも同様の警告が発生します（`across_if_fn` コンテキストに応じてメッセージが変わります）
- `c_across()` 関数にも同様の非推奨警告があります（`id = "dplyr-c-across-missing-cols"`）

---

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

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

### 推奨読解順序

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

まず、`across()` の引数構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | across.R | `R/across.R` | `across()` 関数のシグネチャと `.cols` 引数の位置を理解する |

**読解のコツ**: `enquo()` と `quo_is_missing()` によるquosureの処理パターンを理解することが重要です。

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

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

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

**主要処理フロー**:
1. **行216**: `across()` 関数の定義（`function(.cols, .fns, ..., .names = NULL, .unpack = FALSE)`）
2. **行223**: `.cols <- enquo(.cols)` でquosureにキャプチャ
3. **行227-230**: `quo_is_missing(.cols)` チェックと警告発行

#### Step 3: 非推奨チェック関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | across.R | `R/across.R` | `across_missing_cols_deprecate_warn()` 関数 |

**主要処理フロー**:
- **行849-866**: `across_missing_cols_deprecate_warn()` 関数の完全な実装
- **行850**: `across_if_fn` の取得（`across`、`if_any`、`if_all` のいずれか）
- **行858-865**: `lifecycle::deprecate_warn()` 呼び出し
- **行859-860**: バージョンと対象機能の動的生成
- **行864**: ID "dplyr-across-missing-cols"

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

```
across(.fns = fn)  # .cols省略
    │
    ├─ enquo(.cols)
    │
    └─ quo_is_missing(.cols)
           │
           └─ TRUE: across_missing_cols_deprecate_warn()
                  │
                  ├─ context_peek_bare("across_if_fn")
                  │      └─ "across" / "if_any" / "if_all"
                  │
                  └─ lifecycle::deprecate_warn()
                         │
                         └─ 警告メッセージ発行

c_across()  # cols省略
    │
    └─ c_across_missing_cols_deprecate_warn()
           │
           └─ lifecycle::deprecate_warn()
```

### データフロー図

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

.cols省略 ───▶ quo_is_missing() ───▶ TRUE
     │              │                    │
     │              └─▶ deprecate_warn() ─┴─▶ 警告メッセージ
     │
     └──────────────────────────────────────▶ .cols = everything()
```

### 関連ファイル一覧

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