# 通知設計書 120-hintExtendedContext

## 概要

本ドキュメントは、Nimコンパイラにおける`hintExtendedContext`（拡張コンテキストヒント）通知の設計について記述する。

### 本通知の処理概要

`hintExtendedContext`は、デバッグや診断の際により詳細なコンテキスト情報を追跡するためのヒント通知である。コード生成フェーズやセマンティック解析フェーズで、処理中の位置情報を追跡するために使用される。

**業務上の目的・背景**：コンパイラのデバッグにおいて、処理がどのようなコンテキスト（位置情報）で実行されているかを追跡することは、問題の特定に重要である。このヒントが有効な場合、pushInfoContext/popInfoContextによって追跡される情報が拡張され、より詳細なエラー診断が可能になる。

**通知の送信タイミング**：以下のコンテキストでhasHint(hintExtendedContext)が確認される：
1. コード生成フェーズ（ccgstmts.nim）のgenStmts関数
2. セマンティック解析フェーズ（semexprs.nim）のsemExprNoType関数

**通知の受信者**：コンパイルを実行している開発者またはコンパイラ開発者。詳細なコンテキスト情報が追跡される。

**通知内容の概要**：処理中の位置情報がコンテキストスタックにプッシュされ、エラー発生時により詳細な情報が得られる。

**期待されるアクション**：開発者はより詳細なコンテキスト情報を参照し、問題の発生箇所と経緯を特定する。

## 通知種別

コンパイラ出力（コンソール / IDE統合）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期 |
| 優先度 | 低（Hint） |
| リトライ | なし |

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

hintExtendedContextが有効な場合、pushInfoContext/popInfoContextによるコンテキスト追跡が有効化される。verbosityレベル2以下ではデフォルトで無効化されている。

## 通知テンプレート

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

| 項目 | 内容 |
|-----|------|
| 送信元 | Nimコンパイラ |
| 形式 | テキスト |

### 本文テンプレート

```
{コンテキスト情報}
```

直接メッセージを出力するというよりも、pushInfoContext/popInfoContextによる追跡制御に使用される。

### 添付ファイル

なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| $1 | コンテキスト情報 | TLineInfo | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| コード生成 | genStmts関数 | conf.hasHint(hintExtendedContext) | 文のコード生成時 |
| セマンティック解析 | semExprNoType関数 | c.config.hasHint(hintExtendedContext) | 式の解析時 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| verbosity <= 2 | デフォルトのverbosityレベル2以下では抑止 |
| hintExtendedContext not in conf.notes | ヒントが無効化されている場合 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[処理開始] --> B{hasHint hintExtendedContext?}
    B -->|Yes| C[pushInfoContext]
    B -->|No| D[通常処理]
    C --> E[処理実行]
    E --> F[popInfoContext]
    F --> G[終了]
    D --> E2[処理実行]
    E2 --> G
```

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

### 参照テーブル一覧

該当なし（コンパイラ内部処理のみ）

### 参照項目詳細

| 参照項目 | 用途 | 取得条件 |
|---------|------|---------|
| conf.m.msgContext | コンテキストスタック | pushInfoContext/popInfoContextで管理 |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| なし | このヒント自体はエラーを発生させない | - |

### リトライ仕様

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

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 制限 | なし |

### 配信時間帯

制限なし

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

コンテキスト情報にはファイルパスと行番号が含まれるため、ログ公開時には注意が必要。

## 備考

- verbosity レベル3で有効になる
- `--hint:ExtendedContext:on/off`オプションで個別に制御可能
- pushInfoContext/popInfoContextと連携して動作

---

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

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

### 推奨読解順序

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

まず、通知の定義と設定について理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | lineinfos.nim | `compiler/lineinfos.nim` | TMsgKind列挙型のhintExtendedContext定義（114行目）、MsgKindToStr配列でのメッセージテンプレート（243行目） |

**読解のコツ**: hintExtendedContextは"$1"テンプレートを持つが、主にpushInfoContext/popInfoContextの制御に使用される。

#### Step 2: コード生成での使用を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ccgstmts.nim | `compiler/ccgstmts.nim` | genStmts関数（1958-1964行目） |

**主要処理フロー**:
1. **1961行目**: `let isPush = p.config.hasHint(hintExtendedContext)`で有効性確認
2. **1962行目**: `if isPush: pushInfoContext(p.config, t.info)`でコンテキストをプッシュ
3. **1963行目**: `expr(p, t, a)`で実際の処理
4. **1964行目**: `if isPush: popInfoContext(p.config)`でコンテキストをポップ

#### Step 3: セマンティック解析での使用を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | semexprs.nim | `compiler/semexprs.nim` | semExprNoType関数（1202-1207行目） |

**主要処理フロー**:
1. **1203行目**: `let isPush = c.config.hasHint(hintExtendedContext)`で有効性確認
2. **1204行目**: `if isPush: pushInfoContext(c.config, n.info)`でコンテキストをプッシュ
3. **1205-1206行目**: semExprとdiscardCheckで実際の処理
4. **1207行目**: `if isPush: popInfoContext(c.config)`でコンテキストをポップ

#### Step 4: verbosity設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | lineinfos.nim | `compiler/lineinfos.nim` | computeNotesVerbosity関数（263-271行目）、レベル2からhintExtendedContextを除外（266行目） |

**主要処理フロー**:
- **266行目**: result[2]からhintExtendedContextを除外（つまりレベル3以上で有効）

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

```
処理開始
    │
    ├─ コード生成 (ccgstmts.nim)
    │      │
    │      └─ genStmts
    │             │
    │             ├─ hasHint(hintExtendedContext)確認
    │             │
    │             ├─ pushInfoContext (有効時)
    │             │
    │             ├─ expr処理
    │             │
    │             └─ popInfoContext (有効時)
    │
    └─ セマンティック解析 (semexprs.nim)
           │
           └─ semExprNoType
                  │
                  ├─ hasHint(hintExtendedContext)確認
                  │
                  ├─ pushInfoContext (有効時)
                  │
                  ├─ semExpr処理
                  │
                  └─ popInfoContext (有効時)
```

### データフロー図

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

ノード情報 ────────────▶ hasHint確認 ───────────▶ コンテキスト追跡
(TLineInfo)                   │
                              │
                     pushInfoContext
                              │
                         処理実行
                              │
                     popInfoContext
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| lineinfos.nim | `compiler/lineinfos.nim` | ソース | TMsgKind定義、メッセージテンプレート、verbosity設定 |
| ccgstmts.nim | `compiler/ccgstmts.nim` | ソース | コード生成でのコンテキスト追跡 |
| semexprs.nim | `compiler/semexprs.nim` | ソース | セマンティック解析でのコンテキスト追跡 |
| msgs.nim | `compiler/msgs.nim` | ソース | pushInfoContext/popInfoContext関数 |
