bitclust-core 1.3.0 → 1.6.0

data/test/test_searchpage_command.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+require 'test/unit'
+require 'json'
+require 'fileutils'
+require 'bitclust'
+require 'bitclust/methoddatabase'
+require 'bitclust/subcommands/searchpage_command'
+
+# searchpage サブコマンド: 複数バージョンの DB から /ja/search/ 置換用の
+# 静的検索ページ一式（index.html + 統合 search_data.js + JS/CSS アセット）を
+# 生成する。rurema-search（サーバ常駐の全文検索）のリタイア先。
+#
+# テストリスト:
+# [x] 統合 index: 全版共通エントリは versions に全版、片方だけのものはその版のみ
+# [x] index.html に search_versions（昇順）と検索 UI の要素が埋まる
+# [x] vendored JS + NOTICE + search_page.js + search.css がコピーされる
+# [x] ページ専用 UI なので search_init.js（ページ内ボックス用）は含めない
+# [x] DB を持たない引数なし呼び出しはエラー
+# [x] グローバル --database 不要（needs_database? が false）
+class TestSearchpageCommand < Test::Unit::TestCase
+  def setup
+    @tmpdir = "searchpage_test_tmp"
+    FileUtils.rm_rf(@tmpdir)
+    @db34 = build_db('3.4', <<~'RD')
+      description
+
+      = class Foo < Object
+      == Instance Methods
+      --- foo
+    RD
+    @db41 = build_db('4.1', <<~'RD')
+      description
+
+      = class Foo < Object
+      == Instance Methods
+      --- foo
+      --- bar
+    RD
+    @out = "#{@tmpdir}/out"
+  end
+
+  def teardown
+    FileUtils.rm_rf(@tmpdir)
+  end
+
+  def build_db(version, builtin_rd)
+    root = "#{@tmpdir}/tree-#{version}/refm/api/src"
+    FileUtils.mkdir_p("#{root}/_builtin")
+    File.write("#{root}/LIBRARIES", "_builtin\n")
+    File.write("#{root}/_builtin.rd", builtin_rd)
+    prefix = "#{@tmpdir}/db-#{version}"
+    db = BitClust::MethodDatabase.new(prefix)
+    db.init
+    db.transaction do
+      db.propset('version', version)
+      db.propset('encoding', 'utf-8')
+    end
+    db.transaction do
+      db.update_by_stdlibtree(root)
+    end
+    prefix
+  end
+
+  def run_command(argv)
+    cmd = BitClust::Subcommands::SearchpageCommand.new
+    cmd.parse(argv)
+    cmd.exec(argv, { prefix: nil, capi: false })
+    cmd
+  end
+
+  def test_needs_no_global_database_option
+    cmd = BitClust::Subcommands::SearchpageCommand.new
+    assert_false cmd.needs_database?
+  end
+
+  def test_merged_index_versions
+    run_command(["--outputdir=#{@out}", @db41, @db34])
+    js = File.read("#{@out}/js/search_data.js")
+    assert_match(/\Avar search_data = \{/, js)
+    data = JSON.parse(js.sub(/\Avar search_data = /, '').sub(/;\z/, ''))
+    foo = data['index'].find { |e| e['full_name'] == 'Foo#foo' }
+    bar = data['index'].find { |e| e['full_name'] == 'Foo#bar' }
+    klass = data['index'].find { |e| e['full_name'] == 'Foo' }
+    assert_equal %w[3.4 4.1], foo['versions']
+    assert_equal %w[4.1], bar['versions']
+    assert_equal %w[3.4 4.1], klass['versions']
+  end
+
+  def test_merged_index_shows_module_functions_as_question_dot_only
+    # bitclust#279 コメント対応: 版によって表示が ".#"(4.0 より前)と
+    # "?."(4.0 以降)に割れる module function は、統合ページでは "?."
+    # 表記の1エントリに合流させる(両表記が併記されるとわかりにくい)
+    db33 = build_db('3.3', <<~'RD')
+      description
+
+      = module Kernel
+      == Module Functions
+      --- at_exit{ ... } -> Proc
+      aaa
+    RD
+    db40 = build_db('4.0', <<~'RD')
+      description
+
+      = module Kernel
+      == Module Functions
+      --- at_exit{ ... } -> Proc
+      aaa
+    RD
+    run_command(["--outputdir=#{@out}", db40, db33])
+    js = File.read("#{@out}/js/search_data.js")
+    data = JSON.parse(js.sub(/\Avar search_data = /, '').sub(/;\z/, ''))
+    entries = data['index'].select { |e| e['name'] == 'at_exit' }
+    assert_equal ['Kernel?.at_exit'], entries.map { |e| e['full_name'] }
+    assert_equal %w[3.3 4.0], entries[0]['versions']
+    assert_not_match(/Kernel\.#/, js)
+  end
+
+  def test_index_html_embeds_versions_and_ui
+    run_command(["--outputdir=#{@out}", @db41, @db34])
+    html = File.read("#{@out}/index.html")
+    assert_match(/var search_versions = \["3\.4","4\.1"\];/, html)
+    assert_match(/var search_version_base = "\.\.\/";/, html)
+    assert_match(/id="search-field"/, html)
+    assert_match(/id="search-results"/, html)
+    assert_match(%r{js/search_data\.js}, html)
+    assert_match(%r{js/search_page\.js}, html)
+  end
+
+  def test_assets_are_copied
+    run_command(["--outputdir=#{@out}", @db41, @db34])
+    %w[search_navigation.js search_ranker.js search_controller.js
+       search_page.js NOTICE].each do |f|
+      assert File.exist?("#{@out}/js/#{f}"), "js/#{f} not copied"
+    end
+    assert File.exist?("#{@out}/search.css")
+    # ページ内ドロップダウン用の search_init.js はこのページでは使わない
+    assert_false File.exist?("#{@out}/js/search_init.js")
+  end
+
+  def test_no_database_arguments_is_an_error
+    cmd = BitClust::Subcommands::SearchpageCommand.new
+    argv = ["--outputdir=#{@out}"]
+    cmd.parse(argv)
+    assert_raise(SystemExit) do
+      capture_stderr { cmd.exec(argv, { prefix: nil, capi: false }) }
+    end
+  end
+
+  def test_missing_outputdir_is_an_error
+    cmd = BitClust::Subcommands::SearchpageCommand.new
+    argv = [@db34]
+    cmd.parse(argv)
+    assert_raise(SystemExit) do
+      capture_stderr { cmd.exec(argv, { prefix: nil, capi: false }) }
+    end
+  end
+
+  private
+
+  def capture_stderr
+    orig = $stderr
+    $stderr = StringIO.new
+    yield
+  ensure
+    $stderr = orig
+  end
+end

data/test/test_simplesearcher.rb

@@ -15,6 +15,12 @@ class TestSearcher <  Test::Unit::TestCase
 == Class Methods
 --- bar
 = reopen Kernel
+== Module Functions
+--- open
+
+== Instance Methods
+--- puts
+
 == Special Variables
 --- $spespe
 
@@ -45,4 +51,26 @@ HERE
     assert_equal([], search_pattern(@db, " "), 'space')
     assert_equal([], search_pattern(@db, ""), 'blank')
   end
+
+  # bitclust#250 follow-up: the dynamic server's /search accepts free-text
+  # queries, and a module function may be typed in either notation --
+  # "Kernel.#open" (bitclust's own internal spec-string form, still what
+  # docs for Ruby < 4.0 display) or "Kernel?.open" (what docs for Ruby >=
+  # 4.0 display since #277). Both must resolve to the same method,
+  # regardless of which notation the *query* uses -- the query parser has
+  # no idea (and shouldn't need to know) which doc version the user is
+  # thinking of.
+  def test_module_function_query_notation
+    [['Kernel?.open', 'open'],  # new (>=4.0 display) notation
+     ['Kernel.#open', 'open'],  # existing (bitclust-internal) notation: regression check
+     ['?.open',       'open'],  # bare module-function marker, no class name
+     ['Kernel#puts',  'puts'],  # instance method: unaffected by the "?." change
+    ].each{|q, expected|
+      ret = search_pattern(@db, q)
+      assert_not_equal([], ret, q)
+      assert_equal(expected, ret[0].name, q)
+    }
+    # Singleton-method dot notation ('Hoge.h' => 'hoge' in test_simple_search
+    # above) is also unaffected; kept there rather than duplicated here.
+  end
 end

data/test/test_statichtml_command.rb

@@ -0,0 +1,204 @@
+require 'test/unit'
+require 'tmpdir'
+require 'stringio'
+require 'bitclust'
+require 'bitclust/subcommands/statichtml_command'
+
+class TestStatichtmlURLMapperEx < Test::Unit::TestCase
+  def setup
+    @urlmapper = BitClust::Subcommands::StatichtmlCommand::URLMapperEx.new(
+      :suffix => 'html',
+      :edit_base_url => 'https://github.com/rurema/doctree/edit/master',
+    )
+  end
+
+  # The edit URL must not contain a line number, so that shifting source lines
+  # does not churn the generated HTML diff.
+  def test_edit_url_has_no_line_number
+    location = BitClust::Location.new('refm/api/src/_builtin/Array', 42)
+    assert_equal('https://github.com/rurema/doctree/edit/master/refm/api/src/_builtin/Array',
+                 @urlmapper.edit_url(location))
+  end
+
+  # A location restored from the database has no line number (nil); the edit URL
+  # must still be a clean file link without a trailing "#L".
+  def test_edit_url_without_line_in_location
+    location = BitClust::Location.new('refm/api/src/_builtin/Array', nil)
+    assert_equal('https://github.com/rurema/doctree/edit/master/refm/api/src/_builtin/Array',
+                 @urlmapper.edit_url(location))
+  end
+end
+
+class TestStatichtmlRunRubyWasm < Test::Unit::TestCase
+  def build_command(themedir, outputdir)
+    cmd = BitClust::Subcommands::StatichtmlCommand.new
+    cmd.instance_variable_set(:@manager_config, { :themedir => Pathname.new(themedir) })
+    cmd.instance_variable_set(:@outputdir, Pathname.new(outputdir))
+    cmd.instance_variable_set(:@verbose, false)
+    cmd
+  end
+
+  def test_option_defaults_to_nil
+    cmd = BitClust::Subcommands::StatichtmlCommand.new
+    assert_nil(cmd.instance_variable_get(:@run_ruby_wasm))
+  end
+
+  def test_option_is_parsed
+    url = 'https://cdn.jsdelivr.net/npm/@ruby/3.4-wasm-wasi@2.9.3-2.9.4/dist/ruby+stdlib.wasm'
+    cmd = BitClust::Subcommands::StatichtmlCommand.new
+    cmd.parse(["--run-ruby-wasm=#{url}"])
+    assert_equal(url, cmd.instance_variable_get(:@run_ruby_wasm))
+  end
+
+  def test_run_js_is_copied
+    Dir.mktmpdir do |dir|
+      themedir = File.join(dir, 'theme')
+      outputdir = File.join(dir, 'out')
+      FileUtils.mkdir_p(File.join(themedir, 'js'))
+      FileUtils.mkdir_p(outputdir)
+      File.write(File.join(themedir, 'js', 'run.js'), "// run\n")
+      File.write(File.join(themedir, 'js', 'run-worker.js'), "// worker\n")
+      cmd = build_command(themedir, outputdir)
+      cmd.send(:copy_run_ruby_wasm_script)
+      assert_true(File.file?(File.join(outputdir, 'js', 'run.js')))
+      assert_true(File.file?(File.join(outputdir, 'js', 'run-worker.js')))
+    end
+  end
+
+  def test_theme_without_run_js_is_tolerated
+    Dir.mktmpdir do |dir|
+      themedir = File.join(dir, 'theme')
+      outputdir = File.join(dir, 'out')
+      FileUtils.mkdir_p(themedir)
+      FileUtils.mkdir_p(outputdir)
+      cmd = build_command(themedir, outputdir)
+      orig_stderr, $stderr = $stderr, StringIO.new
+      begin
+        assert_nothing_raised { cmd.send(:copy_run_ruby_wasm_script) }
+        assert_match(/run\.js not found/, $stderr.string)
+        assert_match(/run-worker\.js not found/, $stderr.string)
+      ensure
+        $stderr = orig_stderr
+      end
+      assert_false(File.exist?(File.join(outputdir, 'js', 'run.js')))
+      assert_false(File.exist?(File.join(outputdir, 'js', 'run-worker.js')))
+    end
+  end
+
+  # A themedir with run.js but not yet upgraded with run-worker.js (or vice
+  # versa) should still copy whichever file it does have, rather than
+  # aborting or silently skipping both.
+  def test_partial_theme_copies_what_it_has
+    Dir.mktmpdir do |dir|
+      themedir = File.join(dir, 'theme')
+      outputdir = File.join(dir, 'out')
+      FileUtils.mkdir_p(File.join(themedir, 'js'))
+      FileUtils.mkdir_p(outputdir)
+      File.write(File.join(themedir, 'js', 'run.js'), "// run\n")
+      cmd = build_command(themedir, outputdir)
+      orig_stderr, $stderr = $stderr, StringIO.new
+      begin
+        cmd.send(:copy_run_ruby_wasm_script)
+        assert_match(/run-worker\.js not found/, $stderr.string)
+      ensure
+        $stderr = orig_stderr
+      end
+      assert_true(File.file?(File.join(outputdir, 'js', 'run.js')))
+      assert_false(File.exist?(File.join(outputdir, 'js', 'run-worker.js')))
+    end
+  end
+end
+
+class TestStatichtmlSitemap < Test::Unit::TestCase
+  def build_command(outputdir)
+    cmd = BitClust::Subcommands::StatichtmlCommand.new
+    cmd.instance_variable_set(:@outputdir, Pathname.new(outputdir))
+    cmd.instance_variable_set(:@verbose, false)
+    cmd
+  end
+
+  def test_option_defaults_to_nil
+    cmd = BitClust::Subcommands::StatichtmlCommand.new
+    assert_nil(cmd.instance_variable_get(:@sitemap_baseurl))
+  end
+
+  def test_option_is_parsed
+    cmd = BitClust::Subcommands::StatichtmlCommand.new
+    cmd.parse(['--sitemap-baseurl=https://docs.ruby-lang.org/ja/3.4/'])
+    assert_equal('https://docs.ruby-lang.org/ja/3.4/',
+                 cmd.instance_variable_get(:@sitemap_baseurl))
+  end
+
+  def test_record_sitemap_path_is_noop_without_baseurl
+    Dir.mktmpdir do |dir|
+      cmd = build_command(dir)
+      cmd.send(:record_sitemap_path, Pathname.new(dir) + 'class' + 'String.html')
+      assert_empty(cmd.instance_variable_get(:@sitemap_paths))
+    end
+  end
+
+  def test_record_sitemap_path_keeps_relative_path
+    Dir.mktmpdir do |dir|
+      cmd = build_command(dir)
+      cmd.instance_variable_set(:@sitemap_baseurl, 'https://docs.ruby-lang.org/ja/3.4/')
+      cmd.send(:record_sitemap_path, Pathname.new(dir) + 'class' + 'String.html')
+      assert_equal(%w[class/String.html], cmd.instance_variable_get(:@sitemap_paths))
+    end
+  end
+
+  def test_create_sitemap_writes_loc_urls
+    Dir.mktmpdir do |dir|
+      cmd = build_command(dir)
+      cmd.instance_variable_set(:@sitemap_paths,
+                                 ['class/String.html', 'method/String/i/upcase.html'])
+      cmd.send(:create_sitemap, Pathname.new(dir), 'https://docs.ruby-lang.org/ja/3.4/')
+      xml = File.read(File.join(dir, 'sitemap.xml'))
+      assert_match(%r{\A<\?xml version="1\.0" encoding="UTF-8"\?>\n}, xml)
+      assert_match(%r{<urlset xmlns="http://www\.sitemaps\.org/schemas/sitemap/0\.9">}, xml)
+      assert_match(%r{<url><loc>https://docs\.ruby-lang\.org/ja/3\.4/class/String\.html</loc></url>}, xml)
+      assert_match(%r{<url><loc>https://docs\.ruby-lang\.org/ja/3\.4/method/String/i/upcase\.html</loc></url>}, xml)
+      assert_match(%r{</urlset>\n\z}, xml)
+    end
+  end
+
+  def test_create_sitemap_adds_trailing_slash_to_baseurl
+    Dir.mktmpdir do |dir|
+      cmd = build_command(dir)
+      cmd.instance_variable_set(:@sitemap_paths, ['class/String.html'])
+      cmd.send(:create_sitemap, Pathname.new(dir), 'https://docs.ruby-lang.org/ja/3.4')
+      xml = File.read(File.join(dir, 'sitemap.xml'))
+      assert_match(%r{<loc>https://docs\.ruby-lang\.org/ja/3\.4/class/String\.html</loc>}, xml)
+    end
+  end
+
+  def test_create_sitemap_escapes_special_characters
+    Dir.mktmpdir do |dir|
+      cmd = build_command(dir)
+      cmd.instance_variable_set(:@sitemap_paths, ['method/String/i/=3d=3d.html'])
+      cmd.send(:create_sitemap, Pathname.new(dir), 'https://example.com/a&b/')
+      xml = File.read(File.join(dir, 'sitemap.xml'))
+      assert_match(%r{<loc>https://example\.com/a&amp;b/method/String/i/=3d=3d\.html</loc>}, xml)
+      assert_not_match(/a&b/, xml)
+    end
+  end
+
+  def test_create_sitemap_warns_and_truncates_beyond_limit
+    Dir.mktmpdir do |dir|
+      cmd = build_command(dir)
+      limit = BitClust::Subcommands::StatichtmlCommand::MAX_SITEMAP_URLS
+      paths = (1..(limit + 1)).map {|i| "class/C#{i}.html" }
+      cmd.instance_variable_set(:@sitemap_paths, paths)
+      orig_stderr, $stderr = $stderr, StringIO.new
+      begin
+        cmd.send(:create_sitemap, Pathname.new(dir), 'https://example.com/')
+        assert_match(/warning:.*#{limit}/, $stderr.string)
+      ensure
+        $stderr = orig_stderr
+      end
+      xml = File.read(File.join(dir, 'sitemap.xml'))
+      assert_equal(limit, xml.scan('<url>').size)
+      assert_match(%r{<loc>https://example\.com/class/C1\.html</loc>}, xml)
+      assert_not_match(/C#{limit + 1}\.html/, xml)
+    end
+  end
+end

data/test/test_syntax_highlighter.rb

@@ -82,4 +82,64 @@ class TestSyntaxHighlighter < Test::Unit::TestCase
     END
     assert_equal(expected, highlight(source))
   end
+
+  test 'symbol const' do
+    source = <<~END
+      class Foo
+        def to_hash
+          {:Bar => 'a',
+           :Baz => 'b'
+          }
+        end
+      end
+    END
+    expected = <<~END
+      <span class="k">class</span> <span class="nn"></span><span class="o"></span><span class="nc">Foo</span>
+        <span class="k">def</span> <span class="nf">to_hash</span>
+          <span class="p">{</span><span class="ss">:Bar</span> <span class="o">=&gt;</span> <span class="s1">'a'</span>,
+           <span class="ss">:Baz</span> <span class="o">=&gt;</span> <span class="s1">'b'</span>
+          <span class="p">}</span>
+        <span class="k">end</span>
+      <span class="k">end</span>
+    END
+    assert_equal(expected, highlight(source))
+  end
+
+  test 'symbol list' do
+    source = <<~END
+      %i[hellow world].each {|s| p s }
+    END
+    expected = <<~END
+      <span class="ss">%i[hellow world]</span><span class="p">.</span><span class="nf">each</span> <span class="p">{</span><span class="o">|</span>s<span class="o">|</span> <span class="nb">p</span> s <span class="p">}</span>
+    END
+    assert_equal(expected, highlight(source))
+
+    source = <<~END
+      %I[hellow world].each {|s| p s }
+    END
+    expected = <<~END
+      <span class="ss">%I[hellow world]</span><span class="p">.</span><span class="nf">each</span> <span class="p">{</span><span class="o">|</span>s<span class="o">|</span> <span class="nb">p</span> s <span class="p">}</span>
+    END
+    assert_equal(expected, highlight(source))
+  end
+
+  test 'one liner module' do
+    source = <<~END
+      module Foo; end
+    END
+    expected = <<~END
+      <span class="k">module</span> <span class="nn">Foo</span>; <span class="k">end</span>
+    END
+    assert_equal(expected, highlight(source))
+  end
+
+  test 'one liner class' do
+    source = <<~END
+      class Foo; end
+    END
+    expected = <<~END
+      <span class="k">class</span> <span class="nn"></span><span class="o"></span><span class="nc">Foo</span>; <span class="k">end</span>
+    END
+    assert_equal(expected, highlight(source))
+  end
 end

data/test/test_whole_file_gate.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require 'test/unit'
+
+require 'bitclust/whole_file_gate'
+require 'bitclust/include_graph'
+
+# WholeFileGate: ファイル全体を包む単一の版ゲート（#@else 無し）を検出し、
+# スコープの下で不要（常に真）または front matter の since/until で表現できる場合に
+# ゲート行を外す（O4）。表現できないもの（#@else 付き、スコープ外）は据え置き。
+#
+# テストリスト:
+# [x] ゲートで始まらないファイル → detect nil
+# [x] #@end の後に内容が続く（部分ゲート）→ nil
+# [x] ファイル全体を包む #@since/#@until/#@if → Condition
+# [x] トップレベルに #@else がある（fiddle.rd）→ nil
+# [x] 内部にネストしたゲート・#@samplecode があっても正しく対応を取る（rss.rd）
+# [x] 先頭の空行はスキップして判定、#@end の後の空行は許容
+# [x] unwrap: 開き/閉じ行を除去し、先頭に残る空行は削る（doctree 正規化と整合）
+# [x] unwrap_for_scope: スコープ内で常に真の since → [unwrapped, {}]
+# [x] unwrap_for_scope: in-scope の until（fiber/set）→ [unwrapped, {until: v}]
+# [x] unwrap_for_scope: in-scope の since → [unwrapped, {since: v}]
+# [x] unwrap_for_scope: スコープ外（until 2.7.0 等）→ nil（据え置き）
+# [x] unwrap_for_scope: 常に真と証明できる #@if（version >= "X", X <= 下限）→ [unwrapped, {}]
+# [x] unwrap_for_scope: その他の #@if 条件 → nil（据え置き）
+class TestWholeFileGate < Test::Unit::TestCase
+  def scope
+    BitClust::IncludeGraph::Scope.new("3.0", "4.2")
+  end
+
+  def detect(src)
+    BitClust::WholeFileGate.detect(src)
+  end
+
+  def unwrap_for_scope(src)
+    BitClust::WholeFileGate.unwrap_for_scope(src, scope)
+  end
+
+  def test_detect_returns_nil_without_gate
+    assert_nil detect("category Math\n\n本文。\n")
+  end
+
+  def test_detect_returns_nil_for_partial_gate
+    # cgi/util.rd: 先頭ゲートがファイル途中で閉じる
+    assert_nil detect("\#@since 1.9.1\n本文。\n\#@end\n続き。\n")
+  end
+
+  def test_detect_whole_file_since
+    cond = detect("\#@since 1.9.1\n本文。\n\#@end\n")
+    assert_equal :since, cond.kind
+    assert_equal "1.9.1", cond.version
+  end
+
+  def test_detect_whole_file_if
+    cond = detect("\#@if (version >= \"1.8.2\")\n本文。\n\#@end\n")
+    assert_equal :if, cond.kind
+    assert_equal '(version >= "1.8.2")', cond.version
+  end
+
+  def test_detect_returns_nil_with_top_level_else
+    # fiddle.rd: #@until 2.0.0 ... #@else ... #@end
+    assert_nil detect("\#@until 2.0.0\n古い。\n\#@else\n新しい。\n\#@end\n")
+  end
+
+  def test_detect_handles_nested_gates_and_samplecode
+    src = "\#@since 1.9.1\n\#@until 3.0\n本文。\n\#@end\n\#@samplecode\ncode\n\#@end\n\#@end\n"
+    cond = detect(src)
+    assert_equal :since, cond.kind
+  end
+
+  def test_detect_skips_leading_and_trailing_blanks
+    cond = detect("\n\#@since 1.9.1\n本文。\n\#@end\n\n")
+    assert_equal :since, cond.kind
+  end
+
+  def test_unwrap_for_scope_vacuous_since
+    # cmath.rd / _builtin/Encoding: #@since 1.9.1（+直後の空行）で全体が包まれる
+    src = "\#@since 1.9.1\n\ncategory Math\n\n本文。\n\#@end\n"
+    unwrapped, gate = unwrap_for_scope(src)
+    assert_equal "category Math\n\n本文。\n", unwrapped
+    assert_equal({}, gate)
+  end
+
+  def test_unwrap_for_scope_in_scope_until
+    # fiber.rd: #@until 3.1
+    src = "\#@until 3.1\n本文。\n\n\#@end\n"
+    unwrapped, gate = unwrap_for_scope(src)
+    assert_equal "本文。\n\n", unwrapped
+    assert_equal({ until: "3.1" }, gate)
+  end
+
+  def test_unwrap_for_scope_in_scope_since
+    src = "\#@since 3.2\n本文。\n\#@end\n"
+    unwrapped, gate = unwrap_for_scope(src)
+    assert_equal "本文。\n", unwrapped
+    assert_equal({ since: "3.2" }, gate)
+  end
+
+  def test_unwrap_for_scope_leaves_out_of_scope_file
+    # profile.rd / irb/slex.rd: until 2.7.0 は [3.0,4.2) の対象外
+    assert_nil unwrap_for_scope("\#@until 2.7.0\n本文。\n\#@end\n")
+  end
+
+  def test_unwrap_for_scope_provably_true_if
+    # rss.rd: (version >= "1.8.2") はスコープ下限 3.0 以下なので常に真
+    src = "\#@if (version >= \"1.8.2\")\n本文。\n\#@end\n"
+    unwrapped, gate = unwrap_for_scope(src)
+    assert_equal "本文。\n", unwrapped
+    assert_equal({}, gate)
+  end
+
+  def test_unwrap_for_scope_leaves_unprovable_if
+    assert_nil unwrap_for_scope("\#@if (version == \"3.1\")\n本文。\n\#@end\n")
+    assert_nil unwrap_for_scope("\#@if (version >= \"3.1\")\n本文。\n\#@end\n")
+  end
+
+  def test_unwrap_for_scope_returns_nil_without_whole_file_gate
+    assert_nil unwrap_for_scope("category Math\n\n本文。\n")
+  end
+
+  # ---- regate_metadata: 据え置きゲートのメタデータ領域を独立ゲートに分離 ----
+  # 旧版サルベージで据え置かれた library ルートの全体ゲート（rubygems.rd の
+  # #@since 1.9.1 等）は、メタデータが本文に埋もれると native パースが
+  # front matter から読めない。意味等価な正規形（メタデータブロック + 本文ブロック、
+  # それぞれ同じゲートで包む）に書き換えることで、既存のゲート対応
+  # メタデータ収集器がそのまま front matter 化できる
+
+  def regate(src)
+    BitClust::WholeFileGate.regate_metadata(src)
+  end
+
+  def test_regate_metadata_splits_metadata_and_body
+    # 種別（category/require/sublibrary）ごとに独立のゲートブロックへ分ける
+    # （メタデータ収集器の「#@ ブロックは単一種のみ」の制約に合わせる）
+    src = "\#@since 1.9.1\n" \
+          "require rubygems/defaults\n" \
+          "require rubygems/version\n" \
+          "\n" \
+          "sublibrary rubygems/gem_runner\n" \
+          "\n" \
+          "本文。\n" \
+          "\#@end\n"
+    expected = "\#@since 1.9.1\n" \
+               "require rubygems/defaults\n" \
+               "require rubygems/version\n" \
+               "\#@end\n" \
+               "\n" \
+               "\#@since 1.9.1\n" \
+               "sublibrary rubygems/gem_runner\n" \
+               "\#@end\n" \
+               "\n" \
+               "\#@since 1.9.1\n" \
+               "本文。\n" \
+               "\#@end\n"
+    assert_equal expected, regate(src)
+  end
+
+  def test_regate_metadata_skips_leading_blank_in_gate
+    src = "\#@since 1.9.1\n\ncategory Math\n\n本文。\n\#@end\n"
+    expected = "\#@since 1.9.1\ncategory Math\n\#@end\n\n\#@since 1.9.1\n本文。\n\#@end\n"
+    assert_equal expected, regate(src)
+  end
+
+  def test_regate_metadata_returns_nil_without_metadata
+    assert_nil regate("\#@since 1.9.1\n本文。\n\#@end\n")
+  end
+
+  def test_regate_metadata_returns_nil_without_body
+    assert_nil regate("\#@since 1.9.1\nrequire foo\n\#@end\n")
+  end
+
+  def test_regate_metadata_returns_nil_without_whole_file_gate
+    assert_nil regate("require foo\n\n本文。\n")
+  end
+end