# 機能設計書 8-診断機能

## 概要

本ドキュメントは、F#コンパイラの診断機能の設計を記述する。診断機能は、コンパイルエラー・警告メッセージの生成、フォーマット、フィルタリング、出力を担当する機能である。

### 本機能の処理概要

診断機能（CompilerDiagnostics）は、コンパイラの各フェーズで発生したエラー・警告を収集し、開発者にわかりやすいメッセージとして出力する。

**業務上の目的・背景**：コンパイラのエラーメッセージは開発者体験に直結する重要な機能である。的確なエラー位置、わかりやすいメッセージ、適切な重大度分類により、開発者が問題を迅速に特定・修正できるようにする。F#コンパイラは数百種類のエラー・警告コードをサポートし、--warnaserror、--nowarnなどのオプションで柔軟に制御可能。

**機能の利用シーン**：コンパイル時のエラー・警告表示、IDE上のリアルタイム診断、コード分析ツールでの使用。

**主要な処理内容**：
1. 例外からの診断情報抽出
2. エラーコード・メッセージ・位置情報の構築
3. 警告レベルとエラー昇格の判定
4. 診断メッセージのフォーマット（テキスト/構造化）
5. 診断の重複排除とフィルタリング

**関連システム・外部連携**：コンパイラの全フェーズ、IDE統合（FSharpDiagnostic API）と連携する。

**権限による制御**：--warnaserror、--nowarn、--warnon、--warnlevelオプションで診断動作を制御。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 9 | ビルドプロパティページ | 主画面 | 警告レベル、エラー昇格設定 |

## 機能種別

診断・エラー報告処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| exn | Exception | Yes | 発生した例外 | - |
| tcConfig | TcConfig | Yes | コンパイラ設定（警告設定含む） | 初期化済み |

### 入力データソース

- コンパイラ各フェーズからの例外

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| diagnosticMessage | string | フォーマット済みメッセージ |
| errorNumber | int | エラー/警告番号 |
| range | range | ソース位置 |
| severity | FSharpDiagnosticSeverity | Error/Warning/Info |

### 出力先

- コンソール出力
- IDE診断API
- ビルドログ

## 処理フロー

### 処理シーケンス

```
1. 例外キャプチャ
   ├─ 各フェーズからの例外を収集
   └─ DiagnosticsLoggerに記録

2. 診断情報抽出
   ├─ DiagnosticRange取得
   ├─ エラー番号取得
   └─ メッセージ取得

3. 重大度判定
   ├─ --warnaserrorチェック
   ├─ --nowarnチェック
   └─ 警告レベルチェック

4. メッセージフォーマット
   ├─ 位置情報付与
   ├─ 提案メッセージ追加
   └─ 出力形式変換

5. 出力
   └─ コンソール/IDE/ログ出力
```

### フローチャート

```mermaid
flowchart TD
    A[例外発生] --> B[DiagnosticsLoggerに記録]
    B --> C[DiagnosticRange取得]
    C --> D[エラー番号・メッセージ取得]
    D --> E{重大度判定}
    E -->|Error| F[エラーとして出力]
    E -->|Warning| G{warnaserror?}
    G -->|Yes| F
    G -->|No| H{nowarn?}
    H -->|Yes| I[抑制]
    H -->|No| J[警告として出力]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | エラー昇格 | --warnaserrorで指定した警告をエラーに | 常時 |
| BR-002 | 警告抑制 | --nowarnで指定した警告を抑制 | 常時 |
| BR-003 | 警告レベル | --warnlevelで指定したレベル以下を表示 | 常時 |
| BR-004 | 重複排除 | 同一位置の同一診断は1回のみ報告 | 常時 |

### 計算ロジック

診断の重大度は以下の順序で決定：
1. 例外種別からデフォルト重大度を取得
2. --warnaserrorで昇格判定
3. --nowarnで抑制判定
4. 警告レベルでフィルタリング

## データベース操作仕様

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| FS0001-FS9999 | 各種診断 | コンパイル中 | コード修正 |

### リトライ仕様

診断機能自体はリトライ不要。

## トランザクション仕様

該当なし

## パフォーマンス要件

- 診断メッセージ生成は即座に完了
- 大量の診断でもメモリを過度に消費しない

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

特になし

## 備考

F#の診断メッセージはFSComp.resx（リソースファイル）で管理され、多言語対応可能な構造になっている。

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | DiagnosticsLogger.fs | `src/Compiler/Facilities/DiagnosticsLogger.fs` | PhasedDiagnostic、DiagnosticSeverity等の定義 |

#### Step 2: 例外型を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | CompilerDiagnostics.fs | `src/Compiler/Driver/CompilerDiagnostics.fs` | 各種例外定義 |

**主要処理フロー**:
- **47-65行目**: 基本例外型定義（HashIncludeNotAllowedInNonScript等）
- **67-200行目**: DiagnosticRange拡張プロパティ

#### Step 3: メッセージフォーマットを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | CompilerDiagnostics.fs | `src/Compiler/Driver/CompilerDiagnostics.fs` | メッセージ生成関数 |

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

```
例外発生
    │
    ├─ DiagnosticsLogger.ErrorR/Warning
    │      └─ 例外記録
    │
    └─ CompilerDiagnostics
           ├─ GetDiagnosticNumber（番号取得）
           ├─ GetDiagnosticRange（位置取得）
           ├─ OutputDiagnostic（出力）
           └─ FormatDiagnostic（フォーマット）
```

### データフロー図

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

例外（Exception）   ──▶  診断情報抽出            ──▶  番号・位置・メッセージ
                              │
                              ▼
TcConfig           ──▶  重大度判定              ──▶  Error/Warning/抑制
(警告設定)                    │
                              ▼
診断情報           ──▶  フォーマット            ──▶  出力文字列
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| CompilerDiagnostics.fs | `src/Compiler/Driver/CompilerDiagnostics.fs` | ソース | 診断メイン |
| DiagnosticsLogger.fs | `src/Compiler/Facilities/DiagnosticsLogger.fs` | ソース | 診断ログ |
| DiagnosticMessage.fs | `src/Compiler/Facilities/DiagnosticMessage.fs` | ソース | メッセージ定義 |
| FSComp.resx | `src/Compiler/FSComp.resx` | リソース | エラーメッセージ |
