# 通知設計書 11-errRstNewSectionExpected

## 概要

本ドキュメントは、Nimコンパイラのドキュメント生成機能（docgen）およびRST/Markdownパーサーにおけるセクション構造エラー通知「errRstNewSectionExpected」の設計について記述する。

### 本通知の処理概要

errRstNewSectionExpectedは、reStructuredText（RST）またはMarkdownドキュメントの解析中に、セクション（見出し）構造に問題が検出された場合に発生するエラー通知である。

**業務上の目的・背景**：RSTおよびMarkdownドキュメントでは、見出しレベルが階層的に構造化される必要がある。この通知は、セクションの開始が期待される箇所で適切なセクション構文が見つからない場合、または見出しレベルのスキップ（例：レベル1からレベル3へ直接ジャンプ）が検出された場合にユーザーに警告し、ドキュメント構造の一貫性を維持することを目的とする。

**通知の送信タイミング**：以下の状況でRST/Markdownパーサーがドキュメントを解析する際に発生する：
1. セクション見出しの下線/上線が短すぎる場合
2. 見出しレベルが連続していない場合（中間レベルのスキップ）
3. 構文エラーにより新しいセクションが期待される箇所でパースに失敗した場合

**通知の受信者**：Nimコンパイラを使用してドキュメント生成（nim doc）を実行している開発者。

**通知内容の概要**：エラーが発生したファイル名、行番号、列番号、および失敗の詳細理由（下線が短い、レベルスキップなど）を含むエラーメッセージ。

**期待されるアクション**：開発者はエラーメッセージに基づいてRST/Markdownドキュメントのセクション構造を修正する。具体的には、見出しの下線長さを調整するか、欠落している中間レベルの見出しを追加する。

## 通知種別

コンパイラ標準エラー出力（stderr）

## 送信仕様

### 基本情報

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

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

コンパイラのエラー出力設定（`ConfigRef.m.errorOutputs`）に基づいて、標準エラー出力またはフックされたハンドラに送信される。IDEツールモード（nimsuggest等）の場合は構造化エラーフックを通じて送信される。

## 通知テンプレート

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

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

### 本文テンプレート

```
{ファイルパス}({行番号}, {列番号}) Error: new section expected {詳細理由}
```

### 添付ファイル

なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| $1 | 詳細理由（下線が短い、レベルスキップ等） | RSTパーサー解析結果 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| ドキュメント生成 | RST/Markdown解析 | セクション構造エラー検出 | parseSection, checkHeadingHierarchy等での失敗 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| errorsAsWarnings | roPreferMarkdownオプション有効かつスタンドアロンドキュメントでない場合、エラーが警告に降格 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[RST/Markdownパース開始] --> B[セクション構造解析]
    B --> C{セクション構造チェック}
    C -->|下線長チェック失敗| D[meNewSectionExpected発行]
    C -->|レベルスキップ検出| D
    C -->|構文エラー| D
    D --> E[docgen.compilerMsgHandler]
    E --> F[errRstNewSectionExpectedに変換]
    F --> G{errorsAsWarnings?}
    G -->|Yes| H[警告として出力しRecoverableError発生]
    G -->|No| I[globalErrorとして出力]
    H --> J[終了]
    I --> J
```

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

### 参照テーブル一覧

該当なし（ファイルベース処理）

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 下線長不足 | セクション見出しの下線が見出し文字列より短い | 下線を見出し文字列と同等以上の長さに延長 |
| レベルスキップ | 見出しレベルが連続していない | 欠落レベルの見出しを追加 |
| 構文エラー | 予期しないトークン | ドキュメント構文を確認・修正 |

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

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

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

- ファイルパス情報がエラーメッセージに含まれるが、ローカル環境での開発作業を前提としているため特別な対策は不要
- サンドボックスモードでのドキュメント生成時には一部ディレクティブが制限される（roSandboxDisabledオプション）

## 備考

- このエラーはRST/Markdownパーサー（lib/packages/docutils/rst.nim）で発生し、docgen（compiler/docgen.nim）を通じてコンパイラメッセージシステムに伝播される
- Markdownモード（roPreferMarkdown）では、エラーが警告に降格されることがある

---

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

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

### 推奨読解順序

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

RSTパーサーで使用されるメッセージ種別とエラーハンドリングの仕組みを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | rst.nim | `lib/packages/docutils/rst.nim` | MsgKind列挙型のmeNewSectionExpected定義（66行目） |
| 1-2 | lineinfos.nim | `compiler/lineinfos.nim` | TMsgKind列挙型のerrRstNewSectionExpected定義（40行目） |

**読解のコツ**: MsgKindはRSTパーサー内部で使用され、TMsgKindはコンパイラ全体で使用される。両者のマッピングはdocgen.nimで行われる。

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

RST/Markdownドキュメント解析のエントリーポイントと、セクション構造チェックの呼び出し箇所を特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | rst.nim | `lib/packages/docutils/rst.nim` | parseDoc関数（3218-3221行目）でトップレベル解析 |
| 2-2 | rst.nim | `lib/packages/docutils/rst.nim` | parseSectionWrapper関数でセクション構造解析 |

**主要処理フロー**:
1. **3218-3221行目**: parseDoc関数でドキュメント全体をパース、終了時にtkEofでなければmeGeneralParseErrorを発行
2. **3194行目**: rnLeafノードに対してmeNewSectionExpectedを発行
3. **2237行目**: セクション見出しチェック失敗時にmeNewSectionExpectedを発行
4. **2582行目**: 見出しレベルスキップ検出時にmeNewSectionExpectedを発行

#### Step 3: メッセージ変換レイヤーを理解する

RSTパーサーのMsgKindからコンパイラのTMsgKindへの変換処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | docgen.nim | `compiler/docgen.nim` | compilerMsgHandler関数（242-277行目）でメッセージ変換 |

**主要処理フロー**:
- **253行目**: meNewSectionExpected -> errRstNewSectionExpectedへの変換

#### Step 4: エラー出力処理を理解する

コンパイラのメッセージシステムによるエラー出力処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | msgs.nim | `compiler/msgs.nim` | liMessage関数でエラー出力制御 |
| 4-2 | msgs.nim | `compiler/msgs.nim` | globalError/localErrorテンプレート |

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

```
nim doc (ドキュメント生成コマンド)
    │
    ├─ docgen.nim::generateDoc
    │      │
    │      └─ rst.nim::rstParse
    │             │
    │             ├─ parseDoc
    │             │      └─ parseSectionWrapper
    │             │             └─ parseSection
    │             │                    └─ checkHeadingHierarchy (2582行目)
    │             │                           └─ rstMessage(meNewSectionExpected)
    │             │
    │             └─ rstMessage (meNewSectionExpected発行)
    │
    └─ docgen.nim::compilerMsgHandler (253行目)
           │
           └─ msgs.nim::globalError (errRstNewSectionExpected)
                  │
                  └─ liMessage (エラー出力)
```

### データフロー図

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

RST/Markdownファイル ───▶ rst.nim::parseSection ───▶ MsgKind(meNewSectionExpected)
                              │
                              ▼
                         docgen.nim::compilerMsgHandler
                              │
                              ▼
                         TMsgKind(errRstNewSectionExpected)
                              │
                              ▼
                         msgs.nim::globalError/localError
                              │
                              ▼
                         stderr / 構造化エラーフック
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| rst.nim | `lib/packages/docutils/rst.nim` | ソース | RST/Markdownパーサー本体 |
| rstast.nim | `lib/packages/docutils/rstast.nim` | ソース | RST AST定義 |
| docgen.nim | `compiler/docgen.nim` | ソース | ドキュメント生成器、メッセージハンドラ |
| lineinfos.nim | `compiler/lineinfos.nim` | ソース | TMsgKind列挙型定義 |
| msgs.nim | `compiler/msgs.nim` | ソース | コンパイラメッセージシステム |
