bitclust-core 1.3.0 → 1.6.0

data/test/test_rrd_to_markdown.rb

@@ -0,0 +1,968 @@
+# frozen_string_literal: true
+
+require 'test/unit'
+
+require 'bitclust/rrd_to_markdown'
+require 'bitclust/markdown_to_rrd'
+
+class TestRRDToMarkdown < Test::Unit::TestCase
+  def convert(rrd)
+    BitClust::RRDToMarkdown.convert(rrd)
+  end
+
+  # M2: 本文バッククォートの GFM 忠実化。
+  # GNU 風引用 `token'（rd に適切なマークアップがなかった代替記法）は
+  # インラインコードスパン `token` に変換し、それ以外の生バッククォートは
+  # \` にエスケープする（GFM で偶発スパンにならないように）
+
+  def test_gnu_quote_becomes_code_span
+    assert_equal "長いオプションは `-` の代わりに `--` で始まります。\n",
+      convert("長いオプションは `-' の代わりに `--' で始まります。\n")
+  end
+
+  def test_gnu_quote_with_symbols
+    assert_equal "`{}` や `**/` は使用できません。\n",
+      convert("`{}' や `**/' は使用できません。\n")
+  end
+
+  def test_lone_backtick_is_escaped
+    # 対にならない・GNU 引用でもない生バッククォートはエスケープ
+    assert_equal "コード中の \\` は特別です。\n",
+      convert("コード中の ` は特別です。\n")
+  end
+
+  def test_backtick_pair_with_space_is_escaped
+    # 空白を含む `...' は GNU 引用とみなさない（誤検出防止）
+    assert_equal "\\`wget url' のように書きます。\n",
+      convert("`wget url' のように書きます。\n")
+  end
+
+  def test_no_escape_inside_emlist
+    rrd = "//emlist{\nout = `wget url`\n//}\n"
+    assert_equal "```\nout = `wget url`\n```\n", convert(rrd)
+  end
+
+  def test_auto_code_span_not_escaped
+    # __WORD__ の自動コードスパンのバッククォートはエスケープしない
+    assert_equal "`__FILE__` を返します。\n",
+      convert("__FILE__ を返します。\n")
+  end
+
+  def test_no_auto_span_inside_md_ref
+    # Delegator 型: 参照ターゲット内の __WORD__ はスパン化しない
+    # （保護対象は変換後の一重括弧 [m:...]。二重括弧ではない）
+    assert_equal "`__FILE__` と [m:Delegator#__getobj__] を参照。\n",
+      convert("__FILE__ と [[m:Delegator#__getobj__]] を参照。\n")
+  end
+
+  def test_backtick_adjacent_to_auto_span
+    # 生バッククォートが __WORD__ に隣接しても双方向で壊れない
+    rrd = "`__FILE__ を参照。\n"
+    md = convert(rrd)
+    assert_equal "\\``__FILE__` を参照。\n", md
+    assert_equal rrd, BitClust::MarkdownToRRD.convert(md)
+  end
+
+  def test_backtick_in_anchored_heading
+    # spec/pattern_matching 型: 見出し内の対バッククォートはエスケープして温存
+    rrd = "===[a:x] 付記B: `未定義` の振る舞いの例\n"
+    md = convert(rrd)
+    assert_equal "### 付記B: \\`未定義\\` の振る舞いの例 {#x}\n", md
+    assert_equal rrd, BitClust::MarkdownToRRD.convert(md)
+  end
+
+  def test_lone_backtick_heading
+    # symref 型: 見出しがバッククォート1文字
+    rrd = "===[a:ac] `\n"
+    md = convert(rrd)
+    assert_equal "### \\` {#ac}\n", md
+    assert_equal rrd, BitClust::MarkdownToRRD.convert(md)
+  end
+
+  def test_gnu_quote_with_backslash_not_spanned
+    # DOSISH 型: `\' をスパン化すると `\` が \` エスケープと曖昧になるため除外
+    rrd = "2 byte 目が 0x5c(`\\') である文字。\n"
+    md = convert(rrd)
+    assert_equal "2 byte 目が 0x5c(\\`\\') である文字。\n", md
+    assert_equal rrd, BitClust::MarkdownToRRD.convert(md)
+  end
+
+  def test_dlist_term_with_backslash_not_spanned
+    # symref 型: バックスラッシュを含む term はコードスパン化しない
+    rrd = ": xxx \\\n  説明。\n"
+    md = convert(rrd)
+    assert_equal "- **xxx \\**:\n  説明。\n", md
+    assert_equal rrd, BitClust::MarkdownToRRD.convert(md)
+  end
+
+  def test_tex_double_quote_not_spanned
+    # rdoc.rd 型: TeX 風二重引用 ``text'' はスパン化せずエスケープで温存
+    rrd = "二重引用符: \"text\" もしくは ``text''\n"
+    md = convert(rrd)
+    assert_equal "二重引用符: \"text\" もしくは \\`\\`text''\n", md
+    assert_equal rrd, BitClust::MarkdownToRRD.convert(md)
+  end
+
+  def test_dlist_description_across_directives
+    # pack-template 型: dd の説明は #@ 指令行を透過して続く
+    # （ゲート行で打ち切ると後続インデント行がコード扱いになり、
+    # 版解決後の描画が RDCompiler と食い違う）
+    rrd = ": term\n  説明。\n\#@since 2.0\n  追加説明。\n\#@end\n\n本文。\n"
+    md = convert(rrd)
+    assert_equal "- **`term`**:\n  説明。\n\#@since 2.0\n  追加説明。\n\#@end\n\n本文。\n", md
+    assert_equal rrd, BitClust::MarkdownToRRD.convert(md)
+  end
+
+  def test_dlist_description_across_samplecode
+    # pack-template 型: dd 内の #@samplecode 後の字下げ行も dd 段落継続。
+    # 空行スキャンが #@samplecode を透過するとコード本体の行（カラム0）を見て
+    # dd を打ち切り、後続段落がトップレベル pre と誤分類される。
+    # フェンスは CommonMark で dd にネストするよう内容カラム(2桁)へインデント
+    # される（新 MDCompiler の INDENTED_FENCE_RE が取り込む対象）
+    rrd = ": w\n\n  説明。\n\n\#@samplecode\n[0].pack(\"w\")\n\#@end\n\n  なお、後続の説明。\n"
+    md = convert(rrd)
+    assert_equal "- **`w`**:\n\n  説明。\n\n  ```ruby\n  [0].pack(\"w\")\n  ```\n\n  なお、後続の説明。\n", md
+    assert_equal rrd, BitClust::MarkdownToRRD.convert(md)
+  end
+
+  def test_ulist_followed_by_samplecode
+    # news/2_5_0 型: リスト項目直後のカラム0 #@samplecode は項目の外
+    # （RDCompiler は ul を閉じて独立ブロックとして描画する）。
+    # 項目収集が生のまま素通しすると本体の #=> 行が \# エスケープされ、
+    # 版解決後の //emlist 内にエスケープが残って描画が壊れる
+    rrd = "  * 項目\n\#@samplecode\nCoverage.result\n#=> [1]\n\#@end\n  * 次の項目\n"
+    md = convert(rrd)
+    assert_equal "  - 項目\n```ruby\nCoverage.result\n#=> [1]\n```\n  - 次の項目\n", md
+    assert_equal rrd, BitClust::MarkdownToRRD.convert(md)
+  end
+
+  def test_param_continuation_after_gate_end
+    # fileutils 型: ゲートで分岐した @param の継続行が #@end の直後に来る。
+    # nest 0 の #@end（dd より前に開いたゲートの閉じ）も透過しないと
+    # 継続行がコードフェンス化され、版解決後の描画が dd 継続にならない
+    rrd = "\#@since 2.4.0\n@param options :a が指定できます。\n\#@else\n@param options :b が指定できます。\n\#@end\n               [[ref:c:FileUtils#options]]\n"
+    md = convert(rrd)
+    assert_equal "\#@since 2.4.0\n- **param** `options` -- :a が指定できます。\n\#@else\n- **param** `options` -- :b が指定できます。\n\#@end\n               [ref:c:FileUtils#options]\n", md
+    assert_equal rrd, BitClust::MarkdownToRRD.convert(md)
+  end
+
+  def test_gnu_quote_roundtrip
+    rrd = "= module M\n\n`PERMUTE', `RETURN_IN_ORDER' という順序形式と ` の話。\n"
+    md = convert(rrd)
+    assert_equal "# module M\n\n`PERMUTE`, `RETURN_IN_ORDER` という順序形式と \\` の話。\n", md
+    assert_equal rrd, BitClust::MarkdownToRRD.convert(md)
+  end
+
+  # Step 1: H1 ヘッダとパススルー
+
+  def test_module_header
+    assert_equal "# module Comparable\n",
+      convert("= module Comparable\n")
+  end
+
+  def test_class_header_with_superclass
+    assert_equal "# class Array < Object\n",
+      convert("= class Array < Object\n")
+  end
+
+  def test_reopen_header
+    assert_equal "# reopen Kernel\n",
+      convert("= reopen Kernel\n")
+  end
+
+  def test_text_passthrough
+    rrd = "= module Comparable\n\n説明文。\n"
+    expected = "# module Comparable\n\n説明文。\n"
+    assert_equal expected, convert(rrd)
+  end
+
+  def test_directive_passthrough
+    rrd = "= module Comparable\n\n\#@since 2.4.0\ntext\n\#@end\n"
+    expected = "# module Comparable\n\n\#@since 2.4.0\ntext\n\#@end\n"
+    assert_equal expected, convert(rrd)
+  end
+
+  def test_comment_passthrough
+    assert_equal "\#@# これはコメント\n",
+      convert("\#@# これはコメント\n")
+  end
+
+  def test_include_passthrough
+    assert_equal "\#@include(io/buffer.md)\n",
+      convert("\#@include(io/buffer.md)\n")
+  end
+
+  # Step 2: H2 セクションヘッダ
+
+  def test_h2_instance_methods
+    assert_equal "## Instance Methods\n",
+      convert("== Instance Methods\n")
+  end
+
+  def test_h2_class_methods
+    assert_equal "## Class Methods\n",
+      convert("== Class Methods\n")
+  end
+
+  def test_h2_constants
+    assert_equal "## Constants\n",
+      convert("== Constants\n")
+  end
+
+  # Step 3: メソッドシグネチャ + コードブロック
+
+  def test_instance_method_signature
+    # B1: 空白を保持（正規化しない）
+    assert_equal "### def ==(other)    -> bool\n",
+      convert("--- ==(other)    -> bool\n")
+  end
+
+  def test_method_signature_whitespace_preserved
+    assert_equal "### def [](nth)    -> object | nil\n",
+      convert("--- [](nth)    -> object | nil\n")
+  end
+
+  def test_method_signature_with_block
+    assert_equal "### def new(size) {|index| ... }    -> Array\n",
+      convert("--- new(size) {|index| ... }    -> Array\n")
+  end
+
+  def test_multiple_signatures
+    rrd = "--- [](nth) -> object | nil\n--- at(nth) -> object | nil\n"
+    expected = "### def [](nth) -> object | nil\n### def at(nth) -> object | nil\n"
+    assert_equal expected, convert(rrd)
+  end
+
+  def test_code_block_with_label
+    rrd = "\#@samplecode 例\n1 == 1   # => true\n\#@end\n"
+    expected = "```ruby title=\"例\"\n1 == 1   # => true\n```\n"
+    assert_equal expected, convert(rrd)
+  end
+
+  def test_code_block_without_label
+    rrd = "\#@samplecode\n1 == 1\n\#@end\n"
+    expected = "```ruby\n1 == 1\n```\n"
+    assert_equal expected, convert(rrd)
+  end
+
+  def test_samplecode_label_with_backslash
+    rrd = "\#@samplecode \"\\n\" を含む例\n1\n\#@end\n"
+    expected = "```ruby title=\"\\\"\\\\n\\\" を含む例\"\n1\n```\n"
+    assert_equal expected, convert(rrd)
+  end
+
+  def test_emlist_with_caption_and_lang
+    rrd = "//emlist[例][ruby]{\nputs 'hello'\n//}\n"
+    expected = "```ruby title=\"例\"\nputs 'hello'\n```\n"
+    assert_equal expected, convert(rrd)
+  end
+
+  def test_emlist_without_caption_with_lang
+    rrd = "//emlist[][sh]{\necho hello\n//}\n"
+    expected = "```sh\necho hello\n```\n"
+    assert_equal expected, convert(rrd)
+  end
+
+  def test_emlist_without_caption_without_lang
+    rrd = "//emlist{\nplain text\n//}\n"
+    expected = "```\nplain text\n```\n"
+    assert_equal expected, convert(rrd)
+  end
+
+  def test_emlist_caption_with_double_quote
+    rrd = "//emlist[He said \"hello\"][ruby]{\ncode\n//}\n"
+    expected = "```ruby title=\"He said \\\"hello\\\"\"\ncode\n```\n"
+    assert_equal expected, convert(rrd)
+  end
+
+  # Step 4: ClassName. → self. 変換
+
+  def test_class_method_keeps_classname
+    rrd = "= class Array < Object\n\n--- Array.try_convert(obj) -> Array | nil\n"
+    result = convert(rrd)
+    assert_match(/### def Array\.try_convert\(obj\)/, result)
+  end
+
+  def test_module_method_keeps_classname
+    rrd = "= module Benchmark\n\n--- Benchmark.measure(label) -> Benchmark::Tms\n"
+    result = convert(rrd)
+    assert_match(/### def Benchmark\.measure\(label\)/, result)
+  end
+
+  # Step 5: 定数・グローバル変数
+
+  def test_constant_signature
+    assert_equal "### const CR -> String\n",
+      convert("--- CR -> String\n")
+  end
+
+  def test_constant_without_arrow
+    assert_equal "### const START\n",
+      convert("--- START\n")
+  end
+
+  def test_global_variable_signature
+    assert_equal "### gvar $DEBUG -> bool\n",
+      convert("--- $DEBUG -> bool\n")
+  end
+
+  # module_function
+
+  def test_module_function_signature
+    rrd = "== Module Functions\n\n--- measure(label) -> Benchmark::Tms\n"
+    result = convert(rrd)
+    assert_match(/### module_function def measure\(label\)/, result)
+  end
+
+  # ClassName.method はそのまま保持（返り値なしパターン）
+
+  def test_class_method_keeps_classname_without_nil
+    rrd = "= class Array < Object\n\n--- Array.try_convert(obj) -> Array\n"
+    result = convert(rrd)
+    assert_match(/### def Array\.try_convert\(obj\)/, result)
+  end
+
+  # 大文字始まりメソッド（( がある）
+
+  def test_uppercase_method_with_parens
+    assert_equal "### def DEBUG=(val)\n",
+      convert("--- DEBUG=(val)\n")
+  end
+
+  # .# → ? 参照変換
+
+  def test_module_function_ref
+    assert_equal "テスト [m:Kernel?.open]\n",
+      convert("テスト [[m:Kernel.#open]]\n")
+  end
+
+  # Step 6: @param / @return / @raise
+
+  def test_param
+    assert_equal "- **param** `other` -- 自身と比較したいオブジェクトを指定します。\n",
+      convert("@param other 自身と比較したいオブジェクトを指定します。\n")
+  end
+
+  def test_raise
+    assert_equal "- **raise** `ArgumentError` -- <=> が nil を返したときに発生します。\n",
+      convert("@raise ArgumentError <=> が nil を返したときに発生します。\n")
+  end
+
+  def test_return
+    assert_equal "- **return** -- 説明\n",
+      convert("@return 説明\n")
+  end
+
+  def test_param_with_inline_ref
+    assert_equal "- **param** `obj` -- [c:Range] オブジェクト\n",
+      convert("@param obj [[c:Range]] オブジェクト\n")
+  end
+
+  def test_raise_with_inline_ref
+    assert_equal "- **raise** `TypeError` -- [c:String] 以外\n",
+      convert("@raise TypeError [[c:String]] 以外\n")
+  end
+
+  def test_return_with_inline_ref
+    assert_equal "- **return** -- [c:Array] を返す\n",
+      convert("@return [[c:Array]] を返す\n")
+  end
+
+  def test_return_alignment_spaces_preserved
+    # B2: @return の整列空白を保持
+    assert_equal "- **return** --      説明\n",
+      convert("@return      説明\n")
+  end
+
+  def test_metadata_continuation_line
+    rrd = "@raise ArgumentError self <=> min か、self <=> max が nil を返\n                     したときに発生します。\n"
+    expected = "- **raise** `ArgumentError` -- self <=> min か、self <=> max が nil を返\n                     したときに発生します。\n"
+    assert_equal expected, convert(rrd)
+  end
+
+  # Step 7: @see
+
+  def test_see_single
+    # B3: @see は [[→[ 置換のみ、区切りは保持
+    assert_equal "- **SEE** [m:String#-@]\n",
+      convert("@see [[m:String#-@]]\n")
+  end
+
+  def test_see_multiple_with_comma_space
+    assert_equal "- **SEE** [m:A], [m:B]\n",
+      convert("@see [[m:A]], [[m:B]]\n")
+  end
+
+  def test_see_multiple_without_comma_space
+    # B3: カンマ後スペースなしも保持
+    assert_equal "- **SEE** [m:A],[m:B]\n",
+      convert("@see [[m:A]],[[m:B]]\n")
+  end
+
+  def test_see_class_ref
+    assert_equal "- **SEE** [c:Array]\n",
+      convert("@see [[c:Array]]\n")
+  end
+
+  def test_see_doc_ref
+    assert_equal "- **SEE** [d:spec/m17n]\n",
+      convert("@see [[d:spec/m17n]]\n")
+  end
+
+  # Step 8: YAML front matter
+
+  def test_include_to_front_matter
+    rrd = "= class Array < Object\ninclude Enumerable\n\n説明\n"
+    expected = "---\ninclude:\n  - Enumerable\n---\n# class Array < Object\n\n説明\n"
+    assert_equal expected, convert(rrd)
+  end
+
+  def test_multiple_includes_to_front_matter
+    rrd = "= class Array < Object\ninclude Enumerable\ninclude Comparable\n\n説明\n"
+    expected = "---\ninclude:\n  - Enumerable\n  - Comparable\n---\n# class Array < Object\n\n説明\n"
+    assert_equal expected, convert(rrd)
+  end
+
+  def test_extend_to_front_matter
+    rrd = "= class Foo < Object\nextend Forwardable\n"
+    expected = "---\nextend:\n  - Forwardable\n---\n# class Foo < Object\n"
+    assert_equal expected, convert(rrd)
+  end
+
+  def test_alias_to_front_matter
+    rrd = "= class Integer < Numeric\nalias Fixnum\n"
+    expected = "---\nalias:\n  - Fixnum\n---\n# class Integer < Numeric\n"
+    assert_equal expected, convert(rrd)
+  end
+
+  def test_multi_entity_file_keeps_relations_in_body
+    # 複数エンティティを含むファイルは帰属が曖昧なため front matter 化しない（分割前の安全策）
+    rrd = "= object ARGF < ARGF.class\n\n説明1\n\n= class ARGF.class < Object\ninclude Enumerable\n\n説明2\n"
+    result = convert(rrd)
+    refute_match(/\A---/, result)
+    assert_match(/# class ARGF\.class < Object\ninclude Enumerable/, result)
+  end
+
+  def test_versioned_alias_to_front_matter
+    # 版条件（#@）で囲まれたヘッダ関係は front matter 内に #@ を挟んで表現する（§1.6）
+    rrd = "= class Integer < Numeric\n\n\#@until 3.2\nalias Fixnum\nalias Bignum\n\#@end\n\n説明\n"
+    expected = "---\nalias:\n\#@until 3.2\n  - Fixnum\n  - Bignum\n\#@end\n---\n# class Integer < Numeric\n\n説明\n"
+    assert_equal expected, convert(rrd)
+  end
+
+  # Step 8.3: doc ツリー由来のリテラルエスケープ（refm/doc 対応）
+  # 旧 news 等には「参照や見出しに見えるリテラル本文」があり、
+  # md 側でエスケープしないと md→rd の復元で誤変換される。
+
+  def test_literal_bare_ref_lookalike_is_escaped
+    # news/1_9_0: [ruby-talk:198440] はリテラル本文（参照ではない）
+    rrd = "= class A < Object\n\n無名モジュールの変更\n\\[ruby-talk:198440] を参照。\n"
+    md = convert("= class A < Object\n\n無名モジュールの変更\n[ruby-talk:198440] を参照。\n")
+    assert_match(/\\\[ruby-talk:198440\]/, md)
+  end
+
+  def test_real_refs_are_not_escaped
+    md = convert("= class A < Object\n\n[[m:Array#each]] と [[c:String]] を参照。\n")
+    assert_match(/\[m:Array#each\] と \[c:String\]/, md)
+    refute_match(/\\\[/, md)
+  end
+
+  def test_leading_hash_line_is_escaped
+    # news/1.6.0: 行頭 # のリテラル本文（コメントアウトされた変更履歴）
+    md = convert("= class A < Object\n\n\# : 2002-08-01 IO#read\n\#    本文。\n")
+    assert_match(/^\\# : 2002-08-01 IO#read$/, md)
+    assert_match(/^\\#    本文。$/, md)
+  end
+
+  def test_anchored_h1
+    # spec/rubycmd.rd: =[a:ruby] Rubyの起動
+    assert_equal "# Rubyの起動 {#ruby}\n", convert("=[a:ruby] Rubyの起動\n")
+  end
+
+  def test_heading_trailing_space_is_preserved
+    # news/1.8.2: 「=== 2004-12-06 」（末尾スペース）
+    assert_equal "### 2004-12-06 \n", convert("=== 2004-12-06 \n")
+  end
+
+  # Step 7.5: @param 継続の貪欲さ（RDCompiler の dd_without_p と同規則）
+  # 空白を含む行（"   \n" や字下げの例示ブロック）は @param 説明の継続。
+  # 完全な空行（"\n"）でのみ停止する（CGI::HtmlExtension#popup_menu 型）。
+
+  def test_param_continuation_spans_whitespace_only_lines
+    rrd = "= class A < Object\n== Instance Methods\n--- m(v) -> String\n\n" \
+          "@param v 説明。\n   \n        例：\n        code\n\n本文。\n"
+    md = convert(rrd)
+    assert_match(/-- 説明。\n   \n        例：\n        code\n\n本文。/, md)
+    refute_match(/```/, md)   # 例示ブロックはフェンス化せず継続のまま
+  end
+
+  # Step 7.6: RDCompiler の文脈解釈との整合（描画等価のための変換制約）
+  # RDCompiler は (a) dlist の説明を空行を跨いでインデントが続く限り dd とし
+  # （リスト風の行もテキスト）、(b) 段落中の「: 」行を段落の継続とし、
+  # (c) リスト項目直後のインデント行を深さ不問で項目の継続とする。
+  # 変換器はこの解釈を保存する（構造を変えると描画が変わるため）。
+
+  def test_dlist_description_spans_blank_lines_keeping_list_like_text
+    rrd = ": term\n  説明。\n\n      * 項目風テキスト1\n      * 項目風テキスト2\n\n本文。\n"
+    md = convert(rrd)
+    assert_match(/- \*\*`term`\*\*:\n  説明。\n\n      \* 項目風テキスト1\n      \* 項目風テキスト2\n\n本文。/, md)
+  end
+
+  def test_colon_line_inside_paragraph_stays_text
+    # news/1.8.5 型: テキスト行直後の「: 」行は RDCompiler では段落の継続
+    rrd = "以下のメソッドが追加されました。\n: TCPServer#accept_nonblock [new]\n\n本文。\n"
+    md = convert(rrd)
+    assert_match(/^: TCPServer#accept_nonblock \[new\]$/, md)
+    refute_match(/\*\*/, md)
+  end
+
+  def test_list_continuation_shallower_than_content_indent
+    # news/2_6_0 型: 項目より浅いインデントの行も RDCompiler では項目の継続
+    rrd = "  * 項目の一行目が長くて\n   折り返した継続行。\n\n本文。\n"
+    md = convert(rrd)
+    assert_match(/  - 項目の一行目が長くて\n   折り返した継続行。\n\n本文。/, md)
+    refute_match(/`/, md)
+  end
+
+  # Step 8.35: メタデータ領域の #@# コメント（irb.rd 対応）
+  # メタ行の間に挟まる #@# は front matter 内に保持する（YAML コメントになる）。
+  # メタ領域の後・本文の前の #@#（rss.rd 型）は従来どおり body に残す。
+
+  def test_leading_comment_in_metadata_to_front_matter
+    # irb.rd: ファイル先頭の #@# Author コメント → category の直前に保持
+    rrd = "\#@# Author: Keiju\n\ncategory Development\n\n本文。\n"
+    expected = "---\n\#@# Author: Keiju\ncategory: Development\n---\n本文。\n"
+    assert_equal expected, convert(rrd)
+  end
+
+  def test_comment_inside_require_block_to_front_matter
+    # irb.rd: require 群の途中の #@# 注記 → require ブロック行として保持
+    rrd = "category Development\n\n\#@until 2.7.0\nrequire a\n\#@end\nrequire b\n" \
+          "\#@# note\nrequire c\n\n本文。\n"
+    expected = "---\ncategory: Development\nrequire:\n\#@until 2.7.0\n  - a\n\#@end\n" \
+               "  - b\n\#@# note\n  - c\n---\n本文。\n"
+    assert_equal expected, convert(rrd)
+  end
+
+  def test_comment_directly_above_require_joins_the_block
+    # irb/workspace.rd: 先頭 #@# の直後に空行なしで require が続く
+    # （コメントはその require の説明）→ require ブロックの先頭行として保持
+    rrd = "\#@# CONTEXT_MODE 2 の場合のみ。\nrequire irb/ws-for-case-2\n\n本文。\n"
+    expected = "---\nrequire:\n\#@# CONTEXT_MODE 2 の場合のみ。\n  - irb/ws-for-case-2\n---\n本文。\n"
+    assert_equal expected, convert(rrd)
+  end
+
+  def test_trailing_comment_before_body_stays_in_body
+    # rss.rd 型: メタ確定後の #@# は本文の前置き → body 据え置き（既存動作の維持）
+    rrd = "category FileFormat\n\n\#@# = rss\n\n説明。\n"
+    expected = "---\ncategory: FileFormat\n---\n\#@# = rss\n\n説明。\n"
+    assert_equal expected, convert(rrd)
+  end
+
+  # Step 8.4: メタデータ領域の部分コミット
+  # メタデータ（category/require/sublibrary）の後に版分岐つき散文や #@# コメントが
+  # 続く場合、nest==0 の空行チェックポイントまでをメタデータとして確定し、
+  # 残りは body に渡す（set.rd / thread.rd / rss.rd パターン）。
+
+  def test_category_lifts_before_versioned_prose
+    # set.rd: category Math + 空行 + 版分岐つき散文
+    rrd = "category Math\n\n\#@since 3.0\n新しい説明\n\#@else\n古い説明\n\#@end\n\n本文。\n"
+    expected = "---\ncategory: Math\n---\n" \
+               "\#@since 3.0\n新しい説明\n\#@else\n古い説明\n\#@end\n\n本文。\n"
+    assert_equal expected, convert(rrd)
+  end
+
+  def test_category_lifts_before_preprocessor_comment
+    # rss.rd: category FileFormat + 空行 + #@# コメント
+    rrd = "category FileFormat\n\n\#@# = rss\n\n説明。\n"
+    expected = "---\ncategory: FileFormat\n---\n\#@# = rss\n\n説明。\n"
+    assert_equal expected, convert(rrd)
+  end
+
+  def test_metadata_without_blank_checkpoint_stays_in_body
+    # 空行チェックポイントが無い（category 直後にゲート）場合は従来どおり据え置き
+    # （md→rd の再生成が category の後に空行を足すため、コミットすると一致しない）
+    rrd = "category Math\n\#@since 3.0\n説明\n\#@end\n"
+    assert_equal "category Math\n\#@since 3.0\n説明\n\#@end\n", convert(rrd)
+  end
+
+  # Step 8.5: extra front matter 注入（クロスファイル・オーケストレータ用）
+  # library 所属・構造 since/until はファイル単体からは分からないため、
+  # include グラフを解析したオーケストレータが注入する。
+
+  def test_extra_front_matter_library
+    rrd = "= class Bar < Object\n\n説明\n"
+    expected = "---\nlibrary: foo\n---\n# class Bar < Object\n\n説明\n"
+    assert_equal expected,
+      BitClust::RRDToMarkdown.convert(rrd, extra_front_matter: { "library" => "foo" })
+  end
+
+  def test_extra_front_matter_ordering_with_collected_relations
+    # §1.7 の順序: library → include/extend/alias → since/until
+    rrd = "= class Bar < Object\ninclude Enumerable\n\n説明\n"
+    expected = "---\nlibrary: foo\ninclude:\n  - Enumerable\nsince: \"3.2\"\n---\n" \
+               "# class Bar < Object\n\n説明\n"
+    assert_equal expected,
+      BitClust::RRDToMarkdown.convert(rrd,
+        extra_front_matter: { "library" => "foo", "since" => "3.2" })
+  end
+
+  def test_extra_front_matter_accepts_symbol_keys
+    # IncludeGraph::Scope#gate は {since:, until:} のシンボルキーを返す
+    rrd = "= class Bar < Object\n"
+    expected = "---\nlibrary: foo\nuntil: \"4.0\"\n---\n# class Bar < Object\n"
+    assert_equal expected,
+      BitClust::RRDToMarkdown.convert(rrd,
+        extra_front_matter: { library: "foo", until: "4.0" })
+  end
+
+  def test_extra_front_matter_gated_library_list
+    # 多重所属（IncludeGraph#front_matter_map のリスト形式）は
+    # ゲート付きリストとして emit する（MARKUP_SPEC §1.2/§1.6）
+    rrd = "= class Mutex < Object\n\n説明\n"
+    expected = "---\n" \
+               "library:\n" \
+               "  - _builtin\n" \
+               "\#@until 1.9.1\n" \
+               "  - thread\n" \
+               "\#@end\n" \
+               "---\n" \
+               "# class Mutex < Object\n\n説明\n"
+    assert_equal expected,
+      BitClust::RRDToMarkdown.convert(rrd, extra_front_matter: {
+        "library" => [
+          { "name" => "_builtin" },
+          { "name" => "thread", "until" => "1.9.1" }
+        ] })
+  end
+
+  def test_extra_front_matter_gated_library_list_with_since_and_both_bounds
+    rrd = "= class Foo < Object\n"
+    expected = "---\n" \
+               "library:\n" \
+               "\#@since 2.3.0\n" \
+               "  - _builtin\n" \
+               "\#@end\n" \
+               "\#@since 1.9.1\n" \
+               "\#@until 2.3.0\n" \
+               "  - thread\n" \
+               "\#@end\n" \
+               "\#@end\n" \
+               "---\n" \
+               "# class Foo < Object\n"
+    assert_equal expected,
+      BitClust::RRDToMarkdown.convert(rrd, extra_front_matter: {
+        "library" => [
+          { "name" => "_builtin", "since" => "2.3.0" },
+          { "name" => "thread", "since" => "1.9.1", "until" => "2.3.0" }
+        ] })
+  end
+
+  def test_gated_metadata_blocks_of_different_kinds
+    # regate_metadata の出力形: require と sublibrary が別々の単一種ゲート
+    # ブロックに分かれている（rubygems.rd の据え置きゲート）。
+    # それぞれの front matter キーへゲートごと振り分ける
+    rrd = "\#@since 1.9.1\nrequire a\nrequire b\n\#@end\n\n" \
+          "\#@since 1.9.1\nsublibrary s\n\#@end\n\n" \
+          "\#@since 1.9.1\n本文。\n\#@end\n"
+    expected = "---\n" \
+               "require:\n" \
+               "\#@since 1.9.1\n" \
+               "  - a\n" \
+               "  - b\n" \
+               "\#@end\n" \
+               "sublibrary:\n" \
+               "\#@since 1.9.1\n" \
+               "  - s\n" \
+               "\#@end\n" \
+               "---\n" \
+               "\#@since 1.9.1\n本文。\n\#@end\n"
+    assert_equal expected, BitClust::RRDToMarkdown.convert(rrd)
+  end
+
+  def test_gated_category_becomes_gated_scalar
+    # cmath.rd の据え置きゲート: category はスカラのままゲート行で挟む
+    # （値の差し替えではなく単一値の存在ゲートなので生 YAML でも重複キーにならない）
+    rrd = "\#@since 1.9.1\ncategory Math\n\#@end\n\n" \
+          "\#@since 1.9.1\n本文。\n\#@end\n"
+    expected = "---\n" \
+               "\#@since 1.9.1\n" \
+               "category: Math\n" \
+               "\#@end\n" \
+               "---\n" \
+               "\#@since 1.9.1\n本文。\n\#@end\n"
+    assert_equal expected, BitClust::RRDToMarkdown.convert(rrd)
+  end
+
+  def test_extra_front_matter_on_multi_entity_file
+    # library はファイル単位の情報なので、マルチエンティティでも曖昧なく注入できる
+    # （ファイル内の全エンティティは同一ライブラリ所属。ヘッダ関係は body 据え置きのまま）
+    rrd = "= object ARGF < ARGF.class\n\n説明1\n\n= class ARGF.class < Object\ninclude Enumerable\n\n説明2\n"
+    result = BitClust::RRDToMarkdown.convert(rrd,
+      extra_front_matter: { "library" => "_builtin" })
+    assert result.start_with?("---\nlibrary: _builtin\n---\n"), result[0, 60].inspect
+    assert_match(/include Enumerable/, result)
+  end
+
+  def test_extra_front_matter_rejects_unknown_keys
+    assert_raise(ArgumentError) do
+      BitClust::RRDToMarkdown.convert("= class Bar < Object\n",
+        extra_front_matter: { "libary" => "typo" })
+    end
+  end
+
+  def test_extra_front_matter_roundtrip_drops_injected_keys
+    # 注入キーはオーケストレータ由来の横断情報なので、md→rd では body に現れず
+    # 元の RD がそのまま復元される
+    require 'bitclust/markdown_to_rrd'
+    rrd = "= class Bar < Object\ninclude Enumerable\n\n説明\n"
+    md = BitClust::RRDToMarkdown.convert(rrd,
+      extra_front_matter: { "library" => "foo", "since" => "3.2" })
+    assert_equal rrd, BitClust::MarkdownToRRD.convert(md)
+  end
+
+  def test_extra_front_matter_name_emitted_after_type
+    # ファイル名の大文字小文字衝突回避で改名されたライブラリファイル
+    # （rdoc/rdoc.lib.md）の名前保持用。順序は type → name（§1.7）
+    rrd = "x/x の説明。\n"
+    expected = "---\ntype: library\nname: x/x\n---\nx/x の説明。\n"
+    assert_equal expected,
+      BitClust::RRDToMarkdown.convert(rrd,
+        extra_front_matter: { "type" => "library", "name" => "x/x" })
+  end
+
+  def test_mixed_gated_alias_and_plain_include_to_front_matter
+    # net/Net__HTTPServerException（分割後）: 版条件つき alias と素の include の混在。
+    # #@ ブロックごとに単一種なら front matter 化できる
+    rrd = "= class A < B\n\#@since 2.6.0\nalias C\n\#@end\ninclude D\n\n説明\n"
+    expected = "---\ninclude:\n  - D\nalias:\n\#@since 2.6.0\n  - C\n\#@end\n---\n" \
+               "# class A < B\n\n説明\n"
+    assert_equal expected, convert(rrd)
+  end
+
+  def test_mixed_kinds_within_one_gate_block_stay_in_body
+    # 1つの #@ ブロック内に複数種はデータ上存在しないので据え置きのまま
+    rrd = "= class A < B\n\#@since 2.6.0\nalias C\ninclude D\n\#@end\n\n説明\n"
+    assert_equal "# class A < B\n\#@since 2.6.0\nalias C\ninclude D\n\#@end\n\n説明\n",
+      convert(rrd)
+  end
+
+  def test_versioned_include_if_to_front_matter
+    rrd = "= class File < IO\n\#@if (version < \"1.8.0\")\ninclude File::Constants\n\#@end\n\n説明\n"
+    expected = "---\ninclude:\n\#@if (version < \"1.8.0\")\n  - File::Constants\n\#@end\n---\n# class File < IO\n\n説明\n"
+    assert_equal expected, convert(rrd)
+  end
+
+  def test_versioned_prose_not_treated_as_header_relation
+    # #@ が本文（関係でない）を包む場合はヘッダ関係扱いしない
+    rrd = "= module Foo\n\n\#@since 3.0\n本文\n\#@end\n"
+    expected = "# module Foo\n\n\#@since 3.0\n本文\n\#@end\n"
+    assert_equal expected, convert(rrd)
+  end
+
+  def test_front_matter_category
+    rrd = "category Network\n\nライブラリの説明\n"
+    result = convert(rrd)
+    assert_match(/\A---\ncategory: Network\n---\n/, result)
+    assert_match(/ライブラリの説明/, result)
+  end
+
+  def test_front_matter_require
+    rrd = "require cgi/core\nrequire cgi/cookie\n\nライブラリの説明\n"
+    result = convert(rrd)
+    assert_match(/require:\n  - cgi\/core\n  - cgi\/cookie\n/, result)
+  end
+
+  def test_front_matter_sublibrary
+    rrd = "sublibrary json/ext\n\nライブラリの説明\n"
+    result = convert(rrd)
+    assert_match(/sublibrary:\n  - json\/ext\n/, result)
+  end
+
+  def test_front_matter_category_and_require
+    rrd = "category Network\n\nrequire socket\n\nライブラリの説明\n"
+    result = convert(rrd)
+    assert_match(/\A---\ncategory: Network\nrequire:\n  - socket\n---\n/, result)
+  end
+
+  def test_versioned_require_to_front_matter
+    rrd = "category Network\n\n\#@since 1.9.1\nrequire cgi/core\nrequire cgi/cookie\n\#@end\n\n説明\n"
+    expected = "---\ncategory: Network\nrequire:\n\#@since 1.9.1\n  - cgi/core\n  - cgi/cookie\n\#@end\n---\n説明\n"
+    assert_equal expected, convert(rrd)
+  end
+
+  def test_file_spanning_version_gate_metadata_stays_in_body
+    # ファイル全体を包む #@（構造的ゲート）はメタを front matter にしない（項目1で対応）
+    rrd = "\#@since 1.9.1\n\ncategory Math\n\n説明\n\#@end\n"
+    result = convert(rrd)
+    refute_match(/\A---/, result)
+    assert_match(/\A\#@since 1.9.1\n/, result)
+  end
+
+  def test_no_front_matter_when_no_metadata
+    rrd = "= module Comparable\n\n説明\n"
+    result = convert(rrd)
+    assert_match(/\A# module Comparable\n/, result)
+    refute_match(/\A---/, result)
+  end
+
+  def test_include_after_blank_line_to_front_matter
+    rrd = "= class String < Object\n\ninclude Comparable\n\n説明\n"
+    expected = "---\ninclude:\n  - Comparable\n---\n# class String < Object\n\n説明\n"
+    assert_equal expected, convert(rrd)
+  end
+
+  # Step 9: アンカー付き見出し・H4
+
+  def test_h3_with_anchor
+    assert_equal "### 破壊的な変更 {#mutable}\n",
+      convert("===[a:mutable] 破壊的な変更\n")
+  end
+
+  def test_h4_heading
+    assert_equal "#### 小見出し\n",
+      convert("==== 小見出し\n")
+  end
+
+  def test_h3_without_anchor
+    assert_equal "### 読み込み\n",
+      convert("=== 読み込み\n")
+  end
+
+  # Step 10: クロスリファレンス（インライン）
+
+  def test_inline_class_ref
+    assert_equal "[c:String] を参照。\n",
+      convert("[[c:String]] を参照。\n")
+  end
+
+  def test_inline_method_ref
+    assert_equal "[m:Array#each] と同じ。\n",
+      convert("[[m:Array#each]] と同じ。\n")
+  end
+
+  def test_inline_multiple_refs
+    assert_equal "[c:Array] と [c:Hash] を使う。\n",
+      convert("[[c:Array]] と [[c:Hash]] を使う。\n")
+  end
+
+  def test_inline_bracket_method_ref
+    # A2: [[m:Hash#[] ]] → [m:Hash#\[\]]
+    assert_equal "- **SEE** [m:Hash#\\[\\]]\n",
+      convert("@see [[m:Hash#[] ]]\n")
+  end
+
+  def test_inline_ref_with_trailing_bracket
+    # [[m:Math::PI]]] → [m:Math::PI]]
+    assert_equal "ら [-self, [m:Math::PI]] を返します。\n",
+      convert("ら [-self, [[m:Math::PI]]] を返します。\n")
+  end
+
+  def test_inline_ref_not_in_code_block
+    rrd = "\#@samplecode\n[[c:String]]\n\#@end\n"
+    expected = "```ruby\n[[c:String]]\n```\n"
+    assert_equal expected, convert(rrd)
+  end
+
+  # Step 11: リスト変換
+
+  def test_unordered_list
+    # B4: 元のインデント幅を保持
+    rrd = " * item1\n * item2\n"
+    expected = " - item1\n - item2\n"
+    assert_equal expected, convert(rrd)
+  end
+
+  def test_unordered_list_2space_indent
+    rrd = "  * item1\n  * item2\n"
+    expected = "  - item1\n  - item2\n"
+    assert_equal expected, convert(rrd)
+  end
+
+  def test_ordered_list
+    rrd = " (1) 最初\n (2) 次\n (3) 最後\n"
+    expected = " 1. 最初\n 2. 次\n 3. 最後\n"
+    assert_equal expected, convert(rrd)
+  end
+
+  def test_text_number_to_bold
+    rrd = "1. テキスト\n"
+    expected = "**1.** テキスト\n"
+    assert_equal expected, convert(rrd)
+  end
+
+  # C1: インデントコードブロック +3
+
+  def test_indented_code_block
+    rrd = "説明\n  code line 1\n  code line 2\n\n次の段落\n"
+    expected = "説明\n`````\ncode line 1\ncode line 2\n`````\n\n次の段落\n"
+    assert_equal expected, convert(rrd)
+  end
+
+  def test_indented_code_block_8spaces
+    rrd = "説明\n        code\n\n"
+    expected = "説明\n```````````\ncode\n```````````\n\n"
+    assert_equal expected, convert(rrd)
+  end
+
+  # Step 12: 定義リスト
+
+  def test_definition_list
+    rrd = ": type\n  Content-Type header\n"
+    expected = "- **`type`**:\n  Content-Type header\n"
+    assert_equal expected, convert(rrd)
+  end
+
+  def test_definition_list_multiple
+    rrd = ": type\n  Content-Type header\n: charset\n  Character set\n"
+    expected = "- **`type`**:\n  Content-Type header\n- **`charset`**:\n  Character set\n"
+    assert_equal expected, convert(rrd)
+  end
+
+  def test_definition_list_multiline
+    rrd = ": [ ]\n  鈎括弧内のいずれかの文字と一致します。- でつな\n  がれた文字は範囲を表します。\n"
+    expected = "- **`[ ]`**:\n  鈎括弧内のいずれかの文字と一致します。- でつな\n  がれた文字は範囲を表します。\n"
+    assert_equal expected, convert(rrd)
+  end
+
+  # __WORD__ コードスパン変換
+
+  def test_add_code_spans_basic
+    assert_match(/`__END__`/, convert("__END__ を使う\n"))
+  end
+
+  # Step 13: 統合テスト — Comparable ラウンドトリップ
+
+  def test_comparable_roundtrip
+    rrd_path = File.expand_path('../../doctree/refm/api/src/_builtin/Comparable', __dir__)
+    omit 'doctree not found' unless File.exist?(rrd_path)
+
+    require 'bitclust/markdown_to_rrd'
+    require 'bitclust/methoddatabase'
+    require 'bitclust/rrdparser'
+
+    params = {"version" => "3.4"}
+
+    # Original → parse
+    db1 = BitClust::MethodDatabase.dummy(params)
+    lib1 = BitClust::RRDParser.new(db1).parse_file(rrd_path, "_builtin", params)
+
+    # RD → MD → RD → parse
+    rrd = File.read(rrd_path)
+    md = BitClust::RRDToMarkdown.convert(rrd)
+    rrd2 = BitClust::MarkdownToRRD.convert(md)
+
+    require 'tempfile'
+    Tempfile.create(['comparable', '.rrd']) do |f|
+      f.write(rrd2)
+      f.flush
+      db2 = BitClust::MethodDatabase.dummy(params)
+      lib2 = BitClust::RRDParser.new(db2).parse_file(f.path, "_builtin", params)
+
+      # 同じクラス/メソッド構造であることを検証
+      orig_methods = lib1.classes.first.entries.map(&:names)
+      roundtrip_methods = lib2.classes.first.entries.map(&:names)
+      assert_equal orig_methods, roundtrip_methods
+    end
+  end
+end