# 通知設計書 25-warnDeprecated

## 概要

本ドキュメントは、Nimコンパイラにおける警告通知「warnDeprecated」の設計仕様を定義する。この警告は、非推奨（deprecated）とマークされた機能、シンボル、または構文が使用された場合に発生する警告である。

### 本通知の処理概要

この通知は、`{.deprecated.}`プラグマでマークされた関数、型、変数、モジュール、または非推奨となった構文・機能が使用された場合に発生する。コンパイラの複数の箇所から呼び出され、Nim言語の後方互換性を維持しながら将来の変更を事前に通知する重要な役割を担う。

**業務上の目的・背景**：言語やライブラリの進化に伴い、古い機能は新しい機能に置き換えられる。非推奨警告を発することで、開発者に対して将来の破壊的変更を事前に通知し、移行の猶予期間を提供する。これにより、コードベースの段階的な更新が可能となり、急激な破壊的変更による混乱を防ぐことができる。

**通知の送信タイミング**：コンパイル時の意味解析フェーズで、以下の状況で送信される：
- `{.deprecated.}`プラグマが付いたシンボルの使用時
- 非推奨となった構文（例：古いimportパス形式、古いプラグマ）の使用時
- 非推奨となったコンパイラ機能の使用時

**通知の受信者**：Nimソースコードをコンパイルしている開発者（標準エラー出力またはIDEツール経由）。

**通知内容の概要**：「$1」形式のメッセージが出力される。$1には非推奨の理由や推奨される代替手段が含まれる（例：「'oldFunc' is deprecated; use 'newFunc' instead」）。

**期待されるアクション**：開発者は警告メッセージを確認し、推奨される代替機能への移行を行う。メッセージに代替手段が記載されている場合はそれに従い、記載されていない場合はドキュメントを参照して適切な移行方法を確認する。

## 通知種別

コンパイラ警告メッセージ（標準エラー出力 / IDE連携）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期 |
| 優先度 | 中（Warning） |
| リトライ | 無し |

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

標準エラー出力（stderr）に出力される。IDEツール（nimsuggest等）使用時は、構造化されたエラーフック経由でIDEに通知される。`--stdout`オプション指定時は標準出力に出力される。

## 通知テンプレート

### コンソール出力の場合

| 項目 | 内容 |
|-----|------|
| 出力先 | stderr（デフォルト）/ stdout（--stdout指定時） |
| 形式 | テキスト |

### 本文テンプレート

```
{ファイル名}({行},{列}) Warning: {非推奨メッセージ} [Deprecated]
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| $1 | 非推奨の詳細メッセージ（理由、代替手段など） | deprecatedプラグマの引数またはコンパイラ内部定義 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| コンパイル | シンボル使用 | `{.deprecated.}`プラグマ付きシンボルの使用 | suggest.nimのwarnAboutDeprecated関数 |
| コンパイル | モジュールインポート | 非推奨モジュールのインポート | importer.nimでの警告 |
| コンパイル | 構文解析 | 古い構文形式の使用 | modulepaths.nim（ドットパス形式）、lexer.nim（古いリテラル形式） |
| コンパイル | プラグマ処理 | 非推奨プラグマの使用 | pragmas.nimでの警告 |
| コンパイル | 文解析 | 非推奨な文の使用 | semstmts.nim（メソッド、フック関連） |
| コンパイル | 型解析 | 非推奨な型構文の使用 | semtypes.nim（リージョン構文など） |
| コンパイル | 式解析 | 非推奨な式の使用 | semexprs.nim（bind文など） |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| --warning:Deprecated:off | この特定の警告が無効化されている場合 |
| --warnings:off | 全ての警告が無効化されている場合 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[シンボル/構文使用検出] --> B{非推奨マーク?}
    B -->|No| C[正常処理継続]
    B -->|Yes| D[非推奨メッセージ取得]
    D --> E{カスタムメッセージあり?}
    E -->|Yes| F[カスタムメッセージ使用]
    E -->|No| G[デフォルトメッセージ生成]
    F --> H[warnDeprecated発行]
    G --> H
    H --> I[message呼び出し]
    I --> J[liMessage呼び出し]
    J --> K[styledMsgWriteln出力]
    K --> C
```

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

### 参照テーブル一覧

該当なし（メモリ上のシンボルテーブルとプラグマ情報を参照）

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| - | この警告自体はエラーではない | 警告を出力し処理継続 |

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

制限なし（コンパイラ実行時に即座に出力）

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

- シンボル名や非推奨メッセージがログに含まれるが、セキュリティリスクは低い
- ローカル環境でのコンパイル時のみ出力される

## 備考

- Nimコンパイラで最も広く使用されている警告の1つ
- ヘルパー関数`warningDeprecated`（msgs.nim:644）が提供されており、コマンドライン情報を使用したい場合に便利
- `{.deprecated: "理由".}`形式でカスタムメッセージを指定可能
- 関連する警告として`warnConfigDeprecated`（設定ファイルの非推奨）がある

---

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

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

### 推奨読解順序

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

まず、メッセージ種別の定義と警告メッセージの文字列を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | lineinfos.nim | `compiler/lineinfos.nim` | TMsgKind列挙型でwarnDeprecatedの定義（53行目）、MsgKindToStr配列でメッセージ文字列の定義（145行目） |

**読解のコツ**: warnDeprecatedは「Deprecated」という文字列キーを持つ。メッセージテンプレートは単純に「$1」のみで、呼び出し側で完全なメッセージを構築する。

#### Step 2: ヘルパー関数を理解する

warnDeprecatedを簡単に発行するためのヘルパー関数を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | msgs.nim | `compiler/msgs.nim` | warningDeprecated関数（644-645行目）がコマンドライン情報を使用して警告を発行 |

**主要処理フロー**:
- **644行目**: `proc warningDeprecated*` 関数定義
- **645行目**: `message(conf, info, warnDeprecated, msg)` でメッセージ発行

#### Step 3: シンボル非推奨警告を理解する

`{.deprecated.}`プラグマ付きシンボル使用時の警告処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | suggest.nim | `compiler/suggest.nim` | warnAboutDeprecated関数（665-677行目）でプラグマからメッセージを抽出 |

**主要処理フロー**:
- **665行目**: `proc warnAboutDeprecated` 関数開始
- **671-675行目**: プラグマノードからカスタムメッセージを抽出
- **675行目**: メッセージ付きで`warnDeprecated`発行
- **677行目**: デフォルトメッセージで`warnDeprecated`発行

#### Step 4: 構文レベルの非推奨警告を理解する

非推奨構文使用時の警告処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | modulepaths.nim | `compiler/modulepaths.nim` | インポートパスでのドット使用警告（62行目） |
| 4-2 | pragmas.nim | `compiler/pragmas.nim` | 非推奨プラグマ（noForward等）の警告（290-292行目） |
| 4-3 | semstmts.nim | `compiler/semstmts.nim` | 非推奨構文（=フック、ジェネリックメソッド）の警告（2275行目、2411行目） |

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

```
[複数のエントリーポイント]
    │
    ├─ suggest.warnAboutDeprecated (compiler/suggest.nim:665)
    │      └─ シンボル使用時のプラグマチェック
    │
    ├─ modulepaths（ドットパス形式）
    │      └─ localError呼び出し (compiler/modulepaths.nim:62)
    │
    ├─ pragmas（非推奨プラグマ）
    │      └─ message呼び出し (compiler/pragmas.nim:290)
    │
    └─ semstmts/semexprs/semtypes（非推奨構文）
           └─ message呼び出し
                  │
                  └─ liMessage (compiler/msgs.nim:536)
                         │
                         └─ styledMsgWriteln (compiler/msgs.nim:401)
```

### データフロー図

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

シンボル/構文 ───▶ 非推奨チェック ───▶ メッセージ構築 ───▶ warnDeprecated
    │                    │                  │                    │
    └─ プラグマ情報 ────┘                  │                    └─ stderr
                                            │
              カスタム/デフォルトメッセージ ─┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| lineinfos.nim | `compiler/lineinfos.nim` | ソース | TMsgKind列挙型とメッセージ文字列の定義 |
| msgs.nim | `compiler/msgs.nim` | ソース | warningDeprecatedヘルパー関数とメッセージ出力 |
| suggest.nim | `compiler/suggest.nim` | ソース | warnAboutDeprecated関数（プラグマベースの警告） |
| modulepaths.nim | `compiler/modulepaths.nim` | ソース | インポートパス形式の非推奨警告 |
| pragmas.nim | `compiler/pragmas.nim` | ソース | プラグマ自体の非推奨警告 |
| semstmts.nim | `compiler/semstmts.nim` | ソース | 文レベルの非推奨警告（フック、メソッド） |
| semtypes.nim | `compiler/semtypes.nim` | ソース | 型レベルの非推奨警告（リージョン） |
| semexprs.nim | `compiler/semexprs.nim` | ソース | 式レベルの非推奨警告（bind） |
| importer.nim | `compiler/importer.nim` | ソース | モジュールインポート時の非推奨警告 |
| lexer.nim | `compiler/lexer.nim` | ソース | 字句レベルの非推奨警告（古いリテラル形式） |
