# 帳票設計書 8-to md

## 概要

本ドキュメントは、Nushellの`to md`コマンドに関する設計書である。`to md`コマンドは、テーブルデータやリストをMarkdown形式のテキストに変換するデータ変換コマンドである。

### 本帳票の処理概要

`to md`コマンドは、Nushellのテーブルデータ、リスト、レコードをMarkdown形式のテキストに変換する。テーブルはMarkdownテーブル形式で、リストはマーカー付きリスト形式で、特殊レコード（h1, h2, h3, blockquote）はそれぞれの見出し・引用形式で出力される。

**業務上の目的・背景**：Markdownは技術ドキュメント、README、Wiki、ブログ記事など幅広い用途で使用されている軽量マークアップ言語である。Nushellで処理したデータを人間が読みやすく、かつ様々なMarkdownビューワーで表示可能な形式に変換する需要に応える。

**帳票の利用シーン**：
- READMEファイルの自動生成
- ドキュメントへのデータ表の挿入
- レポートの作成
- GitHub/GitLab Issues・PRへのデータ添付
- 技術ブログ記事用データの整形

**主要な出力内容**：
1. Markdownテーブル（レコード/テーブルから変換）
2. Markdownリスト（リストから変換、ordered/unordered/none）
3. 見出し（h1, h2, h3）
4. 引用（blockquote）

**帳票の出力タイミング**：パイプライン処理において`to md`コマンドが実行されたとき

**帳票の利用者**：Nushellユーザー、ドキュメント作成者、開発者

## 帳票種別

データ変換出力（テキスト形式）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| N/A | Nushell CLI | コマンドライン | `to md` コマンド実行 |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | Markdown (テキスト) |
| 用紙サイズ | N/A |
| 向き | N/A |
| ファイル名 | パイプラインで`save`コマンドと組み合わせて指定 |
| 出力方法 | 標準出力またはファイル保存 |
| 文字コード | UTF-8 |

### 出力オプション

| オプション | 短縮形 | 説明 | デフォルト値 |
|-----------|--------|------|-------------|
| --pretty | -p | カラム幅を揃えて整形 | false |
| --per-element | -e | 各行を独立したMarkdown要素として処理 | false |
| --center | -c | 指定カラムを中央寄せ | なし |
| --escape-md | -m | Markdown特殊文字をエスケープ | false |
| --escape-html | -t | HTML特殊文字をエスケープ | false |
| --escape-all | -a | Markdown・HTML両方をエスケープ | false |
| --list | -l | リストスタイル（ordered/unordered/none） | unordered |

## 帳票レイアウト

### レイアウト概要

Markdown出力は入力データに応じて複数の形式を持つ：

#### テーブル形式
```
| column1 | column2 |
| ------- | ------- |
| value1  | value2  |
```

#### リスト形式（unordered）
```
* item1
* item2
* item3
```

#### リスト形式（ordered）
```
1. item1
2. item2
3. item3
```

#### 見出し形式
```
# H1見出し
## H2見出し
### H3見出し
> 引用テキスト
```

### 特殊レコード構文

| レコード形式 | 出力形式 | 例 |
|------------|---------|-----|
| {h1: "text"} | # text | 見出しレベル1 |
| {h2: "text"} | ## text | 見出しレベル2 |
| {h3: "text"} | ### text | 見出しレベル3 |
| {blockquote: "text"} | > text | 引用 |

## 出力条件

### 入力条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| 入力データ型 | Any（任意の型） | Yes |

### リストスタイルオプション

| 値 | 説明 |
|---|------|
| ordered | 番号付きリスト（1. 2. 3.） |
| unordered | マーカー付きリスト（* * *）【デフォルト】 |
| none | マーカーなし |

## データベース参照仕様

### 参照テーブル一覧

本コマンドはデータベースを直接参照しない。パイプラインから受け取るデータを処理する。

## 計算仕様

### 計算項目一覧

| 項目名 | 処理 | 備考 |
|-------|------|------|
| カラム幅計算 | --pretty時に各カラムの最大幅を計算 | パディング適用 |
| 中央寄せ計算 | --center時に中央配置のパディング計算 | 左右均等 |
| エスケープ処理 | Markdown/HTML特殊文字のエスケープ | バックスラッシュ/エンティティ |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[入力データ受信] --> B[オプション解析]
    B --> C{単純リスト?}
    C -->|Yes| D[リストスタイル適用]
    C -->|No| E[group_by処理]
    D --> F[リスト形式出力]
    E --> G{--per-element?}
    G -->|Yes| H[各要素を個別処理]
    G -->|No| I[テーブル形式処理]
    H --> J{要素タイプ判定}
    J -->|List| K[テーブル出力]
    J -->|特殊Record| L[見出し/引用出力]
    J -->|通常Record| M[テーブル出力]
    J -->|その他| N[リスト項目出力]
    K --> O[結果結合]
    L --> O
    M --> O
    N --> O
    I --> O
    F --> O
    O --> P[メタデータ付与]
    P --> Q[PipelineData返却]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| InvalidValue | --listの値が不正 | "valid: one of ordered, unordered, none" | 有効な値を指定 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | メモリ制限内 |
| 目標出力時間 | データサイズに依存 |
| 同時出力数上限 | N/A |

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

- --escape-mdでMarkdown特殊文字をエスケープしてインジェクション防止
- --escape-htmlでHTML特殊文字をエスケープしてXSS防止
- v_htmlescapeクレートを使用した安全なHTMLエスケープ

## 備考

- content_type メタデータは "text/markdown" として設定される（RFC-7763準拠）
- テーブル内のパイプ文字(|)は自動的にエスケープされる
- --prettyオプションで可読性が向上するが、出力サイズは増加する

---

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

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

### 推奨読解順序

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

まず、Markdownの各要素タイプとオプション構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | md.rs | `crates/nu-command/src/formats/to/md.rs` | ListStyle列挙型（12-20行目） |
| 1-2 | md.rs | `crates/nu-command/src/formats/to/md.rs` | ToMdOptions構造体（35-42行目） |
| 1-3 | md.rs | `crates/nu-command/src/formats/to/md.rs` | SPECIAL_MARKDOWN_HEADERS定数（45行目） |

**読解のコツ**: ListStyleの3種類とToMdOptionsの各フィールドが出力にどう影響するか確認する。

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

`to md`コマンドの実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | md.rs | `crates/nu-command/src/formats/to/md.rs` | ToMd構造体とCommandトレイト実装（55-216行目） |

**主要処理フロー**:
1. **60-97行目**: シグネチャ定義（多数のオプション）
2. **172-215行目**: runメソッドでオプション解析とto_md関数呼び出し

#### Step 3: 変換ロジックを理解する

各出力形式の生成ロジックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | md.rs | `crates/nu-command/src/formats/to/md.rs` | to_md関数（218-343行目） |
| 3-2 | md.rs | `crates/nu-command/src/formats/to/md.rs` | table関数（467-560行目） |
| 3-3 | md.rs | `crates/nu-command/src/formats/to/md.rs` | fragment関数（400-444行目） |
| 3-4 | md.rs | `crates/nu-command/src/formats/to/md.rs` | format_list_item関数（346-362行目） |

**主要処理フロー**:
- **231-259行目**: 単純リストの処理
- **262-330行目**: --per-element時の各要素処理
- **467-560行目**: テーブル形式の生成（ヘッダー、セパレータ、データ行）
- **595-705行目**: 出力文字列の組み立て

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

```
ToMd::run (md.rs:172)
    │
    └─ to_md (md.rs:218)
           │
           ├─ [単純リスト時]
           │      │
           │      └─ format_list_item (md.rs:346)
           │
           └─ [テーブル/複合時]
                  │
                  ├─ group_by (md.rs:562)
                  │
                  ├─ table (md.rs:467)
                  │      │
                  │      ├─ merge_descriptors (nu-cmd-base)
                  │      │
                  │      ├─ collect_headers (md.rs:446)
                  │      │
                  │      └─ get_output_string (md.rs:595)
                  │             │
                  │             ├─ get_padded_string (md.rs:725)
                  │             │
                  │             └─ get_centered_string (md.rs:707)
                  │
                  └─ fragment (md.rs:400)
                         │
                         ├─ is_special_markdown_record (md.rs:48)
                         │
                         ├─ 見出し/引用出力
                         │
                         └─ table (テーブルへfallback)
```

### データフロー図

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

Value (Any型) ────────▶ ToMd::run ───────────────────▶ PipelineData::Value
                              │                              │
                              ▼                              ▼
                        to_md                          Markdown文字列
                              │                        "| ... |\n"
                              ▼                        "* ...\n"
                        group_by                       "# ...\n"
                        (同一カラム構造でグループ化)
                              │
                              ├─ table (テーブル生成)
                              │
                              ├─ fragment (見出し/引用生成)
                              │
                              └─ format_list_item (リスト項目生成)
                                    │
                                    ▼
                              metadata付与
                              (text/markdown)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| md.rs | `crates/nu-command/src/formats/to/md.rs` | ソース | to mdコマンドの実装 |
| mod.rs | `crates/nu-command/src/formats/to/mod.rs` | ソース | toモジュールの公開定義 |
| mod.rs | `crates/nu-cmd-base/src/formats/to/mod.rs` | ソース | merge_descriptors関数 |
| v_htmlescape (crate) | 外部依存 | ライブラリ | HTMLエスケープライブラリ |
