# 通知設計書 108-hintPattern

## 概要

本ドキュメントは、Nimコンパイラの`hintPattern`ヒント通知に関する設計を定義する。このヒントは、項書き換えマクロ（term rewriting macro）によるパターンマッチと変換を通知するものである。

### 本通知の処理概要

`hintPattern`ヒントは、Nimコンパイラの高レベル最適化（HLO: High Level Optimization）パスで、項書き換えマクロによるコード変換が適用された際に出力される通知である。

**業務上の目的・背景**：Nimは項書き換えマクロ（`{.pattern.}`プラグマを持つテンプレート/マクロ）を使用してコードパターンを自動的に変換できる。この通知により、開発者はどのパターンがマッチし、コードがどのように変換されたかを追跡でき、最適化の効果を確認したり、意図しない変換が発生していないかデバッグしたりできる。

**通知の送信タイミング**：セマンティック解析フェーズのHLO（高レベル最適化）パスで、パターンがマッチしてコード変換が適用される際に送信される。具体的には`evalPattern`関数内でマクロ/テンプレート展開後に出力される。

**通知の受信者**：コンパイル実行者（開発者）がコンソール出力（stderr）を通じてこの通知を受信する。

**通知内容の概要**：「{元のコード} --> '{変換後のコード}'」という形式で、パターンマッチ前と変換後のコードが表示される。

**期待されるアクション**：開発者はこの通知を確認し、パターンマッチが期待通りに動作しているか検証する。意図しない変換が発生している場合は、パターン定義を見直すか、`--trmacros:off`オプションで最適化を無効化する。

## 通知種別

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

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（コンパイルプロセス内で即時出力） |
| 優先度 | 低（ヒント情報） |
| リトライ | 無し |

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

標準エラー出力（stderr）に送信される。`--stdout`オプションが指定されている場合は標準出力（stdout）に送信される。`writelnHook`が設定されている場合は、そのフック関数に委譲される。

## 通知テンプレート

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

| 項目 | 内容 |
|-----|------|
| メッセージ種別 | Hint |
| フォーマット | `Hint: {パターン} --> '{変換結果}' [Pattern]` |
| 色 | 緑色（HintColor = fgGreen） |

### 本文テンプレート

```
Hint: x + y --> 'optimizedAdd(x, y)' [Pattern]
```

### 添付ファイル

なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| $1 | パターンと変換結果の文字列 | renderTreeで生成 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| セマンティック解析 | パターンマッチ成功 | `hasHint(hintPattern)` かつ `optTrMacros in conf.options` | HLO最適化時 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| optTrMacros not in conf.options | 項書き換えマクロが無効 |
| hintPattern not in conf.notes | 個別にヒントが無効 |
| verbosity = 0 | NotesVerbosity[0]から除外 |
| c.patterns.len == 0 | パターンが登録されていない |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[hloBody/hloStmt: HLO開始] --> B{c.patterns.len > 0?}
    B -->|No| C[スキップ]
    B -->|Yes| D{optTrMacros有効?}
    D -->|No| C
    D -->|Yes| E[hlo関数: ASTトラバース]
    E --> F[applyPatterns]
    F --> G{パターンマッチ?}
    G -->|No| H[サブツリー処理]
    G -->|Yes| I{hasHint hintPattern?}
    I -->|No| J[パターン評価のみ]
    I -->|Yes| K[rule文字列生成: renderTree]
    K --> L[evalPattern]
    L --> M[マクロ/テンプレート展開]
    M --> N[message hintPattern: rule --> result]
```

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

該当なし（ファイルシステムやデータベースへのアクセスなし）

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 該当なし | このヒントは情報出力のみ | - |
| ループ検出 | loopDetector > 300 | warnUserで警告出力 |

### リトライ仕様

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

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 制限なし | パターンマッチごとに出力 |

### 配信時間帯

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

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

- 変換前後のコードがログに出力されるため、機密性の高いコードパターンが露出する可能性
- 通常はアルゴリズムやパターンの情報のみで、セキュリティリスクは低い

## 備考

- `--trmacros:on`（デフォルト）で項書き換えマクロが有効
- `{.pattern.}`プラグマを持つテンプレート/マクロがパターンとして登録される
- ループ検出機構があり、300回以上のネストで警告が出力される
- verbosity 1以上または`--hint:Pattern:on`オプションで有効化可能（デフォルトでは無効）

---

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

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

### 推奨読解順序

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

通知種別の定義とHLO処理の仕組みを理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | lineinfos.nim | `compiler/lineinfos.nim` | TMsgKind列挙型でhintPatternの定義を確認（111行目） |
| 1-2 | lineinfos.nim | `compiler/lineinfos.nim` | MsgKindToStr配列でメッセージ文字列を確認（231行目） |
| 1-3 | lineinfos.nim | `compiler/lineinfos.nim` | NotesVerbosity[0]からhintPatternが除外されていることを確認（271行目） |

**読解のコツ**: hintPatternは"Pattern"という短縮名を持ち、出力時には[Pattern]として表示される。

#### Step 2: HLO処理を理解する

高レベル最適化処理の核心部分を特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | hlo.nim | `compiler/hlo.nim` | evalPattern関数（15-35行目）でパターン評価とヒント出力処理を確認 |
| 2-2 | hlo.nim | `compiler/hlo.nim` | hlo関数（64-95行目）でASTトラバースとパターン適用を理解 |

**主要処理フロー**:
1. **21行目**: `hasHint(hintPattern)`でルール文字列を条件付きで生成
2. **33-35行目**: `hasHint(hintPattern)`でメッセージ出力
3. **34行目**: `message(hintPattern, rule & " --> '" & renderTree(result) & "'")`

#### Step 3: パターンマッチングを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | hlo.nim | `compiler/hlo.nim` | applyPatterns関数（37-62行目）でパターンリストの走査を理解 |

**主要処理フロー**:
- **42行目**: `c.patterns`を逆順でイテレート（後登録優先）
- **45行目**: `applyRule`でパターンマッチを試行
- **56行目**: マッチした場合`evalPattern`を呼び出し

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

```
hloBody / hloStmt (hlo.nim 97, 102行目)
    │
    └─ hlo (64行目)
           │
           ├─ applyPatterns (37行目)
           │      │
           │      ├─ for pattern in c.patterns (逆順)
           │      │
           │      └─ applyRule: パターンマッチ試行
           │             │
           │             └─ マッチ成功
           │                    │
           │                    └─ evalPattern (15行目) ← ここでhintPattern出力
           │                           │
           │                           ├─ hasHint(hintPattern) チェック
           │                           │      └─ rule = renderTree(n)
           │                           │
           │                           ├─ semMacroExpr / semTemplateExpr
           │                           │
           │                           └─ message(hintPattern)
           │                                  └─ liMessage → styledMsgWriteln
           │
           └─ 再帰的にサブツリーを処理
```

### データフロー図

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

AST              ───▶ hloBody/hloStmt      ───▶ 最適化対象判定
                       │
                       ▼
                  applyPatterns          ───▶ パターンマッチ試行
                       │
                       ▼
パターンマッチ   ───▶ evalPattern           ───▶ stderr/stdout
                       │                      "Hint: x + y --> 'opt(x,y)'"
                       ▼
                  semMacroExpr/           ───▶ 変換後AST
                  semTemplateExpr
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| lineinfos.nim | `compiler/lineinfos.nim` | ソース | メッセージ種別定義（TMsgKind列挙型） |
| hlo.nim | `compiler/hlo.nim` | ソース | 高レベル最適化、evalPattern、applyPatterns |
| msgs.nim | `compiler/msgs.nim` | ソース | メッセージ出力処理 |
| renderer.nim | `compiler/renderer.nim` | ソース | renderTree関数（AST文字列化） |
| options.nim | `compiler/options.nim` | ソース | optTrMacrosフラグ |
