# 通知設計書 31-c_across missing cols 非推奨

## 概要

本ドキュメントは、dplyrパッケージの`c_across()`関数において、`cols`引数を省略して呼び出した場合に発生する非推奨警告の設計内容を記述したものである。

### 本通知の処理概要

`c_across()`関数は、行単位の集計処理（rowwise操作）において複数の列の値を1つのベクトルとして結合するために使用される関数である。この通知は、ユーザーが`c_across()`を`cols`引数なしで呼び出した場合に、その使用方法がdplyr 1.1.0で非推奨になったことを警告するものである。

**業務上の目的・背景**：`c_across()`を引数なしで呼び出すと、暗黙的に`everything()`が適用され、すべての列が対象となる。しかし、この暗黙的な動作は意図しない列の包含を招く可能性があり、コードの明確性と保守性を損なう。明示的に`cols`引数を指定させることで、ユーザーがどの列を処理対象としているかを明確にし、コードの可読性と安全性を向上させることを目的としている。

**通知の送信タイミング**：`c_across()`関数が引数なしで呼び出された時点で、`lifecycle::deprecate_warn()`を通じて警告が発行される。この警告は関数の評価パス内で、実際のデータ処理が行われる前に発生する。具体的には`c_across()`関数の397〜410行目において、`quo_is_missing(cols)`が`TRUE`の場合に`c_across_missing_cols_deprecate_warn()`が呼び出される。

**通知の受信者**：この警告はRコンソール上で`c_across()`を使用しているデータ分析者・開発者に対して表示される。警告メッセージはRの標準警告機構を通じてユーザーのコンソールに出力される。

**通知内容の概要**：警告メッセージには、`c_across()`を`cols`引数なしで使用することがdplyr 1.1.0で非推奨になったこと、および代わりに`cols`引数を明示的に指定すべきことが含まれる。

**期待されるアクション**：ユーザーは警告を受け取った後、`c_across()`の呼び出しを`c_across(cols = everything())`または適切な列選択式（例：`c_across(x:z)`）に変更することが期待される。

## 通知種別

コンソール警告（R warning）- `lifecycle::deprecate_warn()`経由

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（関数呼び出し時に即座に発行） |
| 優先度 | 中（非推奨警告） |
| リトライ | なし |

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

Rセッション内で`c_across()`を呼び出したユーザーに対して、Rの警告メカニズムを通じて通知される。警告の表示は`lifecycle_verbosity`オプションの設定に依存する。

## 通知テンプレート

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

| 項目 | 内容 |
|-----|------|
| 警告種別 | lifecycle deprecation warning |
| バージョン | 1.1.0 |
| 警告ID | dplyr-c-across-missing-cols |

### 本文テンプレート

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

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| when | 非推奨になったバージョン | ハードコード "1.1.0" | Yes |
| what | 非推奨になった機能 | I("Using `c_across()` without supplying `cols`") | Yes |
| details | 追加の指示 | "Please supply `cols` instead." | Yes |
| id | 警告の一意識別子 | "dplyr-c-across-missing-cols" | Yes |
| always | 毎回警告するか | TRUE | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 関数呼び出し | `c_across()`の実行 | `cols`引数が省略されている | quosureが欠損(`quo_is_missing`)の場合に警告発行 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| `lifecycle_verbosity = "quiet"` | lifecycleパッケージのverbosityオプションが"quiet"に設定されている場合、警告は抑制される |
| 同一セッション内での重複 | `always = TRUE`が設定されているため、本警告は毎回発行される（通常のlifecycle警告とは異なる動作） |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[c_across関数呼び出し] --> B{cols引数が指定されているか?}
    B -->|No| C[c_across_missing_cols_deprecate_warn呼び出し]
    B -->|Yes| D[通常処理継続]
    C --> E[lifecycle::deprecate_warn実行]
    E --> F[colsをeverything設定]
    F --> G[c_across_setup呼び出し]
    G --> H[列選択・結合処理]
    D --> G
    H --> I[結果返却]
```

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

### 参照テーブル一覧

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

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 警告発行失敗 | lifecycleパッケージが未インストール | dplyrの依存関係として必ずインストールされるため通常発生しない |

### リトライ仕様

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

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | なし（毎回発行） |
| 1日あたり上限 | なし |

### 配信時間帯

制限なし

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

本通知は技術的な非推奨警告であり、個人情報や機密データを含まない。警告メッセージはユーザーのローカルRコンソールにのみ表示される。

## 備考

- この非推奨警告は`always = TRUE`が設定されているため、セッション内で複数回`c_across()`が引数なしで呼び出された場合、毎回警告が発行される
- 関連する警告として、`across()`関数にも同様の`.cols`省略時の非推奨警告がある（No.30）
- `cols`引数のデフォルト値は以前は`everything()`であったが、明示的な指定を推奨するように変更された
- `user_env = caller_env(2)`により、警告のスタックトレースにおいて適切な呼び出し元が報告される

---

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

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

### 推奨読解順序

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

まず、`c_across()`関数が受け取る引数とquosureの構造を理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | across.R | `R/across.R` | c_across関数の定義（397-410行目）を確認し、cols引数の処理方法を理解する |

**読解のコツ**: `enquo()`によりcols引数がquosureに変換され、`quo_is_missing()`で引数が省略されたかどうかを判定している。

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

処理の起点となる`c_across()`関数を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | across.R | `R/across.R` | c_across関数（397-410行目）- 全体の処理フローを把握する |

**主要処理フロー**:
1. **397行目**: `c_across <- function(cols)` - 関数定義、cols引数を受け取る
2. **398行目**: `mask <- peek_mask()` - データマスクを取得
3. **399行目**: `cols <- enquo(cols)` - cols引数をquosureに変換
4. **401行目**: `if (quo_is_missing(cols))` - colsが省略されたかチェック
5. **402行目**: `c_across_missing_cols_deprecate_warn()` - 警告を発行
6. **403行目**: `cols <- quo_set_expr(cols, expr(everything()))` - デフォルト値を設定

#### Step 3: 警告発行関数を理解する

警告を発行する`c_across_missing_cols_deprecate_warn()`関数の詳細を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | across.R | `R/across.R` | c_across_missing_cols_deprecate_warn関数（868-877行目）- 警告発行ロジック |

**主要処理フロー**:
- **868行目**: 関数定義、`user_env = caller_env(2)`でデフォルト環境を設定
- **869-876行目**: `lifecycle::deprecate_warn()`を呼び出し
- **870行目**: `when = "1.1.0"` - 非推奨になったバージョン
- **871行目**: `what = I("Using \`c_across()\` without supplying \`cols\`")` - 非推奨対象
- **872行目**: `details = "Please supply \`cols\` instead."` - 代替案の指示
- **874行目**: `always = TRUE` - 毎回警告を発行
- **875行目**: `id = "dplyr-c-across-missing-cols"` - 警告の一意識別子

#### Step 4: テストケースを理解する

テストファイルで警告の動作を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | test-across.R | `tests/testthat/test-across.R` | c_acrossの警告テスト（1811-1820行目） |
| 4-2 | across.md | `tests/testthat/_snaps/across.md` | 警告メッセージのスナップショット（914-928行目） |

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

```
c_across(cols) [R/across.R:397]
    │
    ├─ peek_mask() [data mask取得]
    │
    ├─ enquo(cols) [quosure変換]
    │
    ├─ quo_is_missing(cols) [引数省略チェック]
    │      │
    │      └─ c_across_missing_cols_deprecate_warn() [R/across.R:868]
    │             └─ lifecycle::deprecate_warn() [外部パッケージ]
    │
    ├─ quo_set_expr(cols, expr(everything())) [デフォルト設定]
    │
    └─ c_across_setup(cols, mask) [R/across.R:546]
           └─ tidyselect::eval_select() [列選択]
```

### データフロー図

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

cols引数 ─────────────────▶ enquo() ─────────────────────▶ quosure
    │                           │
    │                           ▼
    │                     quo_is_missing()
    │                           │
    │                    (missing)
    │                           │
    │                           ▼
    │           c_across_missing_cols_deprecate_warn()
    │                           │
    │                           ▼
    │                 lifecycle::deprecate_warn()
    │                           │
    └───────────────────────────▼
                          quo_set_expr()
                               │
                               ▼
                       everything()適用
                               │
                               ▼
                     c_across_setup() ─────────────────▶ 列名ベクトル
                               │
                               ▼
                          vec_c() ──────────────────────▶ 結合されたベクトル
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| across.R | `R/across.R` | ソース | c_across関数およびc_across_missing_cols_deprecate_warn関数の定義 |
| test-across.R | `tests/testthat/test-across.R` | テスト | c_acrossの警告動作テスト |
| across.md | `tests/testthat/_snaps/across.md` | スナップショット | 警告メッセージのスナップショット |
| DESCRIPTION | `DESCRIPTION` | 設定 | lifecycleパッケージへの依存関係定義 |
