# 帳票設計書 9-コメント情報

## 概要

本ドキュメントは、ソースコード内のコメント情報をJSON形式で出力する帳票「コメント情報」の設計仕様を定義する。

### 本帳票の処理概要

**業務上の目的・背景**：Prettierはソースコードのフォーマット時にコメントを適切な位置に配置する必要があるため、パース時にコメント情報を収集している。本帳票は、Prettierが認識しているコメント情報を可視化し、コメント配置の問題調査やプラグイン開発時のデバッグを支援する。コメントの位置や種類（ブロック/ライン）を確認することで、フォーマット結果の理解を深めることができる。

**帳票の利用シーン**：コメント配置の問題調査、プラグイン開発時のコメント処理確認、フォーマット結果の問題分析、コメント関連バグの調査など。

**主要な出力内容**：
1. コメント配列（各コメントオブジェクト）
2. コメントの型、位置情報、内容

**帳票の出力タイミング**：CLIで`--debug-print-comments`オプションを指定した際に出力される。

**帳票の利用者**：Prettier開発者、プラグイン開発者

## 帳票種別

デバッグ出力（JSON）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| CLI-01 | コマンドライン | `prettier --debug-print-comments <file>` | コマンド実行 |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | JSON |
| 出力先 | 標準出力 |
| 文字コード | UTF-8 |
| フォーマット | Prettier（jsonパーサー）でフォーマット |

### JSON構造

```json
[
  {
    "type": "CommentBlock",
    "value": " コメント内容 ",
    "start": 0,
    "end": 20,
    "loc": {
      "start": { "line": 1, "column": 0 },
      "end": { "line": 1, "column": 20 }
    }
  },
  {
    "type": "CommentLine",
    "value": " 行コメント",
    "start": 25,
    "end": 40
  }
]
```

## 帳票レイアウト

### レイアウト概要

出力はコメントオブジェクトの配列をJSON化したもの。

```
┌─────────────────────────────────────┐
│              JSON配列                │
├─────────────────────────────────────┤
│  [                                   │
│    {                                 │
│      "type": "CommentBlock",         │
│      "value": "...",                 │
│      ...                             │
│    },                                │
│    {                                 │
│      "type": "CommentLine",          │
│      ...                             │
│    }                                 │
│  ]                                   │
└─────────────────────────────────────┘
```

### 出力項目

| No | 項目名 | 説明 | 型 | 備考 |
|----|-------|------|-----|------|
| 1 | type | コメント種別 | string | CommentBlock / CommentLine等 |
| 2 | value | コメント内容 | string | コメント記号を除いた内容 |
| 3 | start | 開始位置（オフセット） | number | パーサー依存 |
| 4 | end | 終了位置（オフセット） | number | パーサー依存 |
| 5 | loc | 位置情報オブジェクト | object | line, column情報 |
| 6 | loc.start | 開始位置 | object | { line, column } |
| 7 | loc.end | 終了位置 | object | { line, column } |

### コメント種別

| 種別 | 説明 | 例 |
|------|------|-----|
| CommentBlock | ブロックコメント | `/* ... */` |
| CommentLine | 行コメント | `// ...` |
| Block | CSS等のブロックコメント | `/* ... */` |
| Comment | HTML等のコメント | `<!-- ... -->` |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| 入力ファイル | コメント抽出対象のファイル | Yes |
| --parser | 使用するパーサー | No（自動推論可） |

### 処理条件

| 条件 | 処理 |
|------|------|
| --debug-print-comments指定 | コメント出力モードに切り替え |
| コメントあり | コメント配列をJSON化 |
| コメントなし | 空配列`[]`を出力 |

## データフロー仕様

### 入力データ

| データ項目 | 型 | 説明 |
|-----------|-----|------|
| input | string | パース対象のソースコード |
| opt | object | パースオプション（parser等） |
| context.argv.debugPrintComments | boolean | コメント出力フラグ |

### 出力データ

| データ項目 | 型 | 説明 |
|-----------|-----|------|
| comments | array | コメント配列 |
| formatted | string | フォーマット済みJSON文字列 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[format関数] --> B{debugPrintComments?}
    B -->|Yes| C[prettier.formatWithCursor呼び出し]
    C --> D[パース実行]
    D --> E[コメント収集]
    E --> F[comments取得]
    F --> G{comments存在?}
    G -->|Yes| H[JSON.stringify]
    G -->|No| I[空配列]
    H --> J[prettier.format(json)]
    I --> J
    J --> K[結果返却]
    B -->|No| L[通常フォーマット処理]
```

### コメント収集フロー

```mermaid
flowchart TD
    A[formatWithCursor] --> B[coreFormat]
    B --> C[parseText]
    C --> D[parser.parse]
    D --> E[comments配列生成]
    E --> F[printAstToDoc]
    F --> G[コメント位置決定]
    G --> H[結果にcomments含める]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| SyntaxError | 構文エラー | {filename}: SyntaxError: {message} | ソースコード修正 |
| UndefinedParserError | パーサー不明 | No parser could be inferred | --parser指定 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 処理方式 | 非同期処理（async/await） |
| 出力サイズ | コメント数に依存 |

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

- コメント内容にはソースコードの情報が含まれる可能性がある
- デバッグ目的のため、プロダクション環境での使用は非推奨

## 備考

- コメント配列はformatWithCursorの戻り値に含まれる
- 出力は`{ parser: "json" }`でフォーマット
- コメントがない場合は空配列`[]`が出力される

---

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

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

### 推奨読解順序

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

まず、コメント情報の構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | core.js | `src/main/core.js` | coreFormatの戻り値（73行目、178-181行目） |
| 1-2 | constants.js | `src/constants.js` | commentsPropertyInOptions定義 |

**読解のコツ**: formatWithCursorの戻り値には`{ formatted, cursorOffset, comments }`が含まれる。

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

コメント出力のトリガーを特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | format.js | `src/cli/format.js` | debugPrintComments処理（108-117行目） |

**主要処理フロー**:
1. **108行目**: debugPrintComments判定
2. **110-113行目**: formatWithCursor呼び出しとコメント取得
3. **114行目**: JSON.stringify
4. **115行目**: prettier.format（jsonパーサー）

#### Step 3: コメント収集処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | core.js | `src/main/core.js` | coreFormat関数（28-182行目） |
| 3-2 | core.js | `src/main/core.js` | comments取得（73行目） |

**主要処理フロー**:
- **73行目**: opts[commentsPropertyInOptions]でコメント取得
- **141行目, 146行目, 178行目**: 戻り値にcommentsを含める

#### Step 4: パーサーのコメント生成を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | parse.js | `src/main/parse.js` | parseText関数 |
| 4-2 | 各言語パーサー | `src/language-*/parser-*.js` | パーサー固有のコメント収集 |

**読解のコツ**: 各パーサーがコメントを収集する方法はパーサーにより異なる。

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

```
CLI: format() [src/cli/format.js:102]
    │
    └─ (--debug-print-comments時)
           │
           ├─ prettier.formatWithCursor() [src/index.js:66]
           │      │
           │      └─ core.formatWithCursor() [src/main/core.js:324]
           │             │
           │             └─ coreFormat() [src/main/core.js:28]
           │                    │
           │                    ├─ parseText() [src/main/parse.js]
           │                    │      │
           │                    │      └─ parser.parse() → comments生成
           │                    │
           │                    └─ { formatted, cursorOffset, comments }
           │
           ├─ JSON.stringify(comments || [])
           │
           └─ prettier.format({ parser: "json" })
```

### データフロー図

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

ソースコード ──────────▶ parseText()
                              │
                              ▼
                    parser.parse() → comments配列生成
                              │
                              ▼
                    opts[commentsPropertyInOptions] = comments
                              │
                              ▼
                    coreFormat() → { comments }
                              │
                              ▼
                    formatWithCursor() → { comments }
                              │
                              ▼
                    JSON.stringify(comments || [])
                              │
                              ▼
                    prettier.format({ parser: "json" })
                              │
                              ▼
                    整形済みJSON ──────────▶ 標準出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| format.js | `src/cli/format.js` | ソース | debugPrintComments処理 |
| core.js | `src/main/core.js` | ソース | coreFormat、comments収集 |
| constants.js | `src/constants.js` | ソース | commentsPropertyInOptions定義 |
| parse.js | `src/main/parse.js` | ソース | parseText関数 |
| index.js | `src/index.js` | ソース | format、formatWithCursor API |
