# 通知設計書 122-hintMsgOrigin

## 概要

本ドキュメントは、Nimコンパイラの通知種別「hintMsgOrigin」（No.122）に関する設計仕様を定義する。この通知は、コンパイラメッセージ（エラー、警告、ヒント）がコンパイラソースコード内のどの位置から発生したかを示すデバッグ向けヒント通知である。Nim 1.3.5以降で導入された。

### 本通知の処理概要

hintMsgOriginは、Nimコンパイラの内部デバッグおよびコンパイラ開発者向けの機能として設計されたヒント通知である。コンパイラが出力する各メッセージに対して、そのメッセージを発行したコンパイラソースコードの位置（ファイル名、行番号、列番号）を追加で出力する。

**業務上の目的・背景**：コンパイラ開発者やコントリビューターがコンパイラのバグを調査する際、特定のエラーメッセージや警告がコンパイラ内部のどの処理から発生しているかを特定することは重要である。このヒントにより、メッセージの発生源を即座に特定でき、デバッグ効率が大幅に向上する。通常のコンパイラ利用者には不要な情報であるため、デフォルトでは無効化されている。

**通知の送信タイミング**：他のコンパイラメッセージ（エラー、警告、ヒント）が出力された直後に、そのメッセージの発生源情報として送信される。メッセージ出力処理（liMessage関数）内で、mainPackageNotesにhintMsgOriginが含まれている場合に出力される。

**通知の受信者**：主にNimコンパイラの開発者、コントリビューター、およびコンパイラの動作を詳細に調査したいユーザー。

**通知内容の概要**：コンパイラメッセージを発行したコンパイラソースコードのファイルパス、行番号、列番号、および「compiler msg initiated here」というメッセージを出力する。

**期待されるアクション**：コンパイラ開発者は、この情報を使ってコンパイラソースコード内の該当箇所を直接参照し、メッセージ出力ロジックの確認やバグ修正を行うことが期待される。

## 通知種別

コンパイラヒント（Hint）- コンソール出力

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（他のメッセージ出力直後に即座に出力） |
| 優先度 | 低（デバッグ用ヒント） |
| リトライ | 無し |

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

コンパイラの標準エラー出力（stderr）または標準出力（stdout、`--stdout`オプション指定時）に対して送信される。`--hint:MsgOrigin:on`が明示的に指定されている場合、または`mainPackageNotes`にhintMsgOriginが含まれている場合に有効となる。

## 通知テンプレート

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

| 項目 | 内容 |
|-----|------|
| 出力先 | stderr（デフォルト）/ stdout（`--stdout`指定時） |
| 形式 | プレーンテキスト / カラー出力（`--colors:on`指定時） |

### 本文テンプレート

```
{コンパイラソースファイルパス}({行番号}, {列番号}) compiler msg initiated here [MsgOrigin]
```

### 出力例

```
/path/to/nim/compiler/semstmts.nim(1234, 5) compiler msg initiated here [MsgOrigin]
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| $1 | コンパイラメッセージの発生位置情報 | InstantiationInfo（instLoc()マクロ） | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| コンパイル処理 | liMessage関数実行 | hintMsgOrigin in mainPackageNotes | 他のコンパイラメッセージ出力時に追加出力 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| `--hint:MsgOrigin:off`（デフォルト） | ヒントが明示的に無効化されている場合 |
| `--verbosity:0` または `--verbosity:1` | 低冗長性レベルでは無効（NotesVerbosity定義による） |
| `ignoreMsgBecauseOfIdeTools`がtrue | IDEツールモードでメッセージ抑制時 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[コンパイラメッセージ発生] --> B[liMessage関数呼び出し]
    B --> C[メインメッセージ出力]
    C --> D{hintMsgOrigin in mainPackageNotes?}
    D -->|No| E[終了]
    D -->|Yes| F[instLoc()でコンパイラ位置取得]
    F --> G[toFileLineCol変換]
    G --> H[styledMsgWriteln出力]
    H --> I["compiler msg initiated here" 出力]
    I --> E
```

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

### 参照テーブル一覧

本通知はコンパイラ内部のデータ構造を参照するため、外部データベースは使用しない。

| データ構造 | 用途 | 備考 |
|-----------|------|------|
| InstantiationInfo | コンパイラソースコードの位置情報 | Nim標準ライブラリのinstantiationInfo()による |
| ConfigRef.mainPackageNotes | 有効なノート（ヒント）の集合 | TNoteKinds型 |

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

#### InstantiationInfo型

| 参照項目 | 用途 | 取得条件 |
|---------|------|---------|
| filename | コンパイラソースファイル名 | instantiationInfo(-2, fullPaths=true)で取得 |
| line | 行番号 | 同上 |
| column | 列番号 | 同上 |

### 更新テーブル一覧

該当なし（読み取り専用）

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 該当なし | - | 本通知はヒントであり、エラーではない |

### リトライ仕様

該当なし

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 制限 | なし（各メッセージに対して1回出力） |

### 配信時間帯

制限なし（コンパイル実行時に随時出力）

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

- 本通知はコンパイラソースコードのファイルパスと行番号を出力するため、コンパイラのビルド環境情報が露出する
- 本番環境でのコンパイルログには含めないことを推奨
- コンパイラのバージョンや内部構造の推測に利用される可能性がある

## 備考

- Nim 1.3.5で導入された機能
- コンパイラ開発者向けのデバッグ機能であり、通常のユーザーには不要
- `--verbosity:1`（デフォルト）では無効化されている（NotesVerbosity定義による）
- ソースコードコメントに「xxx needs a bit of refactoring to honor `conf.filenameOption`」とあり、将来の改善が検討されている

---

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

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

### 推奨読解順序

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

まず、メッセージ出力システムの基本構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | lineinfos.nim | `compiler/lineinfos.nim` | TMsgKind列挙型のhintMsgOrigin定義（116行目）、「# since 1.3.5」コメント |
| 1-2 | lineinfos.nim | `compiler/lineinfos.nim` | MsgKindToStr配列のhintMsgOriginエントリ（245行目）、メッセージテンプレートは「$1」 |
| 1-3 | msgs.nim | `compiler/msgs.nim` | InstantiationInfo型とinstLoc()マクロ（21-22行目） |

**読解のコツ**: hintMsgOriginのメッセージテンプレートは単純な「$1」であり、実際の出力内容はliMessage関数内で構築される。

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

メッセージ出力処理の起点を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | msgs.nim | `compiler/msgs.nim` | liMessage関数（536-608行目）がメッセージ出力の中核 |

**主要処理フロー**:
1. **536-538行目**: liMessage関数の定義、info2パラメータがInstantiationInfo型
2. **598行目**: hintMsgOrigin in conf.mainPackageNotesのチェック
3. **600-603行目**: hintMsgOrigin出力処理

#### Step 3: 出力処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | msgs.nim | `compiler/msgs.nim` | styledMsgWriteln（401-417行目）でスタイル付き出力 |
| 3-2 | msgs.nim | `compiler/msgs.nim` | toFileLineCol関数（310-312行目）で位置情報をフォーマット |

**主要処理フロー**:
- **600行目**: toFileLineCol(info2)でInstantiationInfoを文字列に変換
- **601行目**: 「compiler msg initiated here」メッセージを出力
- **602行目**: KindFormat % $hintMsgOriginで「[MsgOrigin]」を追加

#### Step 4: 有効化条件を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | lineinfos.nim | `compiler/lineinfos.nim` | computeNotesVerbosity関数（263-271行目） |
| 4-2 | lineinfos.nim | `compiler/lineinfos.nim` | 269行目でhintMsgOriginがverbosity:1で除外される設定 |

**主要処理フロー**:
- **269行目**: result[1]からhintMsgOriginが除外されている
- これにより、デフォルトの冗長性レベル（1）ではhintMsgOriginは無効

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

```
localError / message / globalError など
    │
    └─ liMessage (msgs.nim:536-608)
            │
            ├─ styledMsgWriteln (msgs.nim:596-597)
            │      └─ [メインメッセージ出力]
            │
            └─ [hintMsgOrigin in mainPackageNotes の場合]
                    │
                    └─ styledMsgWriteln (msgs.nim:600-603)
                            │
                            ├─ toFileLineCol(info2) → コンパイラ位置
                            └─ "compiler msg initiated here [MsgOrigin]"
```

### データフロー図

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

instLoc()マクロ ───▶ InstantiationInfo ───▶ liMessage関数
                                                   │
                                                   ▼
                                           toFileLineCol変換
                                                   │
                                                   ▼
                                           styledMsgWriteln ───▶ コンソール出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| lineinfos.nim | `compiler/lineinfos.nim` | ソース | TMsgKind定義、NotesVerbosity設定 |
| msgs.nim | `compiler/msgs.nim` | ソース | メッセージ出力処理、liMessage関数 |
| options.nim | `compiler/options.nim` | ソース | ConfigRef.mainPackageNotes設定 |
