bitclust-core 1.7.0 → 1.8.0

data/test/test_markdown_tree.rb

@@ -366,4 +366,148 @@ class TestMarkdownTree < Test::Unit::TestCase
       "version-range-gated H1 relations must not be flagged"
     assert_equal [], tree.warnings
   end
+
+  # --- front matter ゲート付きリストのディレクティブ(bitclust#331) ---
+  # テストリスト:
+  # [x] #%else は直前ゲートの反転(until → since / since → until)
+  # [x] #%version A...B / A... / ...B / V(単一版)
+  # [x] #%version A...B の #%else は「A 未満」と「B 以上」の 2 membership
+  # [x] #%version V の #%else は except: [V]
+  # [x] 入れ子のゲートは交差(since は max・until は min)
+  # [x] 矛盾する入れ子(単一版 ≠ 単一版)は membership を作らない
+  # [x] #%# コメント行は無視
+  # [x] 未知の #% 行・#%if・対応のない #%else/#%end・二重 #%else・
+  #     リスト終端で閉じていないゲートは ParseError(無音の打ち切りをやめる)
+
+  def membership_scan(list)
+    scan(
+      "a.md" => LIB, "b.md" => LIB, "c.md" => LIB,
+      "a/X.md" => "---\nlibrary:\n#{list}---\n# class X < Object\n"
+    )
+  end
+
+  def memberships_of(list)
+    tree = membership_scan(list)
+    assert_equal [], tree.warnings
+    tree.entities["a/X.md"][:memberships]
+  end
+
+  def test_else_inverts_until
+    assert_equal [
+      { library: "a", until: "3.4" },
+      { library: "b", since: "3.4" },
+    ], memberships_of("#%until 3.4\n  - a\n#%else\n  - b\n#%end\n")
+  end
+
+  def test_else_inverts_since
+    assert_equal [
+      { library: "a", since: "3.4" },
+      { library: "b", until: "3.4" },
+    ], memberships_of("#%since 3.4\n  - a\n#%else\n  - b\n#%end\n")
+  end
+
+  def test_version_range_forms
+    assert_equal [
+      { library: "a", since: "3.1", until: "3.3" },
+      { library: "b", since: "3.1" },
+      { library: "c", until: "3.3" },
+    ], memberships_of(
+      "#%version 3.1...3.3\n  - a\n#%end\n" \
+      "#%version 3.1...\n  - b\n#%end\n" \
+      "#%version ...3.3\n  - c\n#%end\n"
+    )
+  end
+
+  def test_single_version
+    assert_equal [{ library: "a", version: "3.1" }],
+      memberships_of("#%version 3.1\n  - a\n#%end\n")
+  end
+
+  def test_else_of_version_range_splits_into_two_memberships
+    assert_equal [
+      { library: "a", since: "3.1", until: "3.3" },
+      { library: "b", until: "3.1" },
+      { library: "b", since: "3.3" },
+    ], memberships_of("#%version 3.1...3.3\n  - a\n#%else\n  - b\n#%end\n")
+  end
+
+  def test_else_of_single_version_is_except
+    assert_equal [
+      { library: "a", version: "3.1" },
+      { library: "b", except: ["3.1"] },
+    ], memberships_of("#%version 3.1\n  - a\n#%else\n  - b\n#%end\n")
+  end
+
+  def test_nested_gates_intersect
+    assert_equal [
+      { library: "a", since: "3.2", until: "3.4" },
+      { library: "b", since: "3.0", until: "3.2" },
+    ], memberships_of(
+      "#%since 3.0\n#%until 3.4\n#%since 3.2\n  - a\n#%else\n  - b\n#%end\n#%end\n#%end\n"
+    )
+  end
+
+  def test_contradicting_nested_single_versions_yield_no_membership
+    assert_equal [{ library: "b", version: "3.1" }],
+      memberships_of("#%version 3.1\n#%version 3.2\n  - a\n#%end\n  - b\n#%end\n")
+  end
+
+  def test_directive_comment_lines_are_ignored
+    assert_equal [{ library: "a" }, { library: "b", until: "3.4" }],
+      memberships_of("#%# comment\n  - a\n#%until 3.4\n#%# another\n  - b\n#%end\n")
+  end
+
+  def test_at_prefix_else_and_version
+    assert_equal [
+      { library: "a", since: "3.1", until: "3.3" },
+      { library: "b", until: "3.1" },
+      { library: "b", since: "3.3" },
+    ], memberships_of("\#@version 3.1...3.3\n  - a\n\#@else\n  - b\n\#@end\n")
+  end
+
+  def assert_list_parse_error(list, pattern)
+    e = assert_raise(BitClust::ParseError) { membership_scan(list) }
+    assert_match pattern, e.message
+    assert_match(/a\/X\.md:\d+/, e.message, "message must locate the file and line")
+  end
+
+  def test_unknown_directive_in_list_raises
+    assert_list_parse_error("  - a\n#%sinse 3.4\n  - b\n#%end\n", /unknown preprocessor directive/)
+  end
+
+  def test_if_in_list_is_unsupported
+    assert_list_parse_error("#%if (version >= \"3.4\")\n  - a\n#%end\n", /#%if is not supported/)
+  end
+
+  def test_else_without_gate_raises
+    assert_list_parse_error("  - a\n#%else\n  - b\n#%end\n", /no matching/)
+  end
+
+  def test_end_without_gate_raises
+    assert_list_parse_error("  - a\n#%end\n", /no matching/)
+  end
+
+  def test_duplicate_else_raises
+    assert_list_parse_error("#%since 3.4\n  - a\n#%else\n  - b\n#%else\n  - c\n#%end\n", /duplicate/)
+  end
+
+  def test_unterminated_gate_at_list_end_raises
+    assert_list_parse_error("#%since 3.4\n  - a\n", /unterminated/)
+  end
+
+  def test_indented_directive_in_list_raises
+    # 列 0 でない #% 行は Preprocessor でも指令にならない(YAML コメント扱い)。
+    # リスト内で無音にゲートが無視されたりリストが打ち切られたりしないよう、
+    # 指令風のインデント行はエラーにする
+    assert_list_parse_error("  - a\n  #%since 3.0\n  - b\n#%end\n", /must start at column 0/)
+  end
+
+  def test_yaml_comment_in_list_is_ignored
+    assert_equal [{ library: "a" }, { library: "b", since: "3.0" }],
+      memberships_of("  # plain yaml comment\n  - a\n#%since 3.0\n  # another\n  - b\n#%end\n")
+  end
+
+  def test_wrong_version_range_raises
+    assert_list_parse_error("#%version 3.1..3.3\n  - a\n#%end\n", /wrong version range/)
+  end
 end

data/test/test_mdparser.rb

@@ -412,6 +412,45 @@ class TestMDParser < Test::Unit::TestCase
     end
   end
 
+  def test_update_by_markdowntree_else_and_single_version_memberships
+    # bitclust#331: ゲート付き library リストの #@version V（単一版）と #@else。
+    # 3.2 だけ onlylib、それ以外は builtin に属する。版の比較は Gem::Version
+    # なので 3.2.0 の DB でも 3.2 と同じ版として扱う
+    require 'tmpdir'
+    Dir.mktmpdir do |root|
+      write = ->(rel, s) {
+        path = File.join(root, rel)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, s)
+      }
+      write.call('builtin.md', "---\ntype: library\n---\nbuiltin。\n")
+      write.call('onlylib.md', "---\ntype: library\n---\nonlylib。\n")
+      write.call('onlylib/Shared.md', <<~'MD')
+        ---
+        library:
+        #@version 3.2
+          - onlylib
+        #@else
+          - builtin
+        #@end
+        ---
+        # class Shared < Object
+
+        共有クラス。
+      MD
+
+      classes = ->(version) {
+        db = BitClust::MethodDatabase.dummy("version" => version)
+        db.update_by_markdowntree(root)
+        %w[builtin onlylib].map { |lib| db.fetch_library(lib).classes.map(&:name) }
+      }
+      assert_equal [[], %w[Shared]], classes.call("3.2")
+      assert_equal [[], %w[Shared]], classes.call("3.2.0")
+      assert_equal [%w[Shared], []], classes.call("3.4")
+      assert_equal [%w[Shared], []], classes.call("3.0")
+    end
+  end
+
   def test_update_by_markdowntree_parse_error_suggests_gem_update
     # manual/ が新しい bitclust を必要とする記法を含むとき、古い gem では
     # パースエラーになる。原因へたどり着けるよう gem 更新の案内を添える

data/test/test_methods_command.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+require 'test/unit'
+require 'bitclust'
+require 'bitclust/subcommands/methods_command'
+
+class TestMethodsCommand < Test::Unit::TestCase
+  def setup
+    @cmd = BitClust::Subcommands::MethodsCommand.new
+  end
+
+  def test_needs_no_database
+    assert_false(@cmd.needs_database?)
+  end
+
+  def test_content_option_is_not_accepted
+    assert_raise(OptionParser::InvalidOption) do
+      @cmd.parse(['-c', 'Object'])
+    end
+  end
+
+  def test_ri_database_option_is_not_accepted
+    assert_raise(OptionParser::InvalidOption) do
+      @cmd.parse(['--ri-database=/tmp/ri', 'Object'])
+    end
+  end
+
+  def test_diff_and_ruby_options_are_kept
+    assert_nothing_raised do
+      @cmd.parse(['--ruby=3.4.8', '--diff=refm/api/src/_builtin/Object', 'Object'])
+    end
+  end
+end

data/test/test_opensearchdescription_screen.rb

@@ -0,0 +1,39 @@
+require 'test/unit'
+require 'uri'
+require 'bitclust'
+require 'bitclust/screen'
+
+class TestOpenSearchDescriptionScreen < Test::Unit::TestCase
+  SRC = <<'HERE'
+= class Foo
+description
+HERE
+
+  def screen
+    _lib, db = BitClust::RRDParser.parse(SRC, 'testlib', {'version' => '3.4'})
+    datadir = File.expand_path('../data/bitclust', __dir__)
+    manager = BitClust::ScreenManager.new(
+      :templatedir => "#{datadir}/template",
+      :catalogdir => "#{datadir}/catalog",
+      :encoding => 'utf-8',
+      :default_encoding => 'utf-8',
+      :base_url => '',
+      :cgi_url => '/view',
+      :target_version => '3.4'
+    )
+    manager.opensearchdescription_screen(URI.parse('http://example.com/view/opensearchdescription'),
+                                         :database => db)
+  end
+
+  def test_body_is_bare_xml_without_html_layout
+    body = screen.body
+    assert_match(/\A<\?xml/, body)
+    assert_not_include(body, '<html')
+    assert_match(%r{\A<\?xml[^>]*\?>\s*<OpenSearchDescription\b.*</OpenSearchDescription>\s*\z}m, body)
+    assert_include(body, 'http://example.com/view/search')
+  end
+
+  def test_content_type_is_opensearch_xml
+    assert_equal 'application/opensearchdescription+xml; charset=utf-8', screen.content_type
+  end
+end

data/test/test_query_command.rb

@@ -0,0 +1,30 @@
+require 'test/unit'
+require 'stringio'
+require 'tmpdir'
+require 'bitclust'
+require 'bitclust/subcommands/query_command'
+
+class TestQueryCommand < Test::Unit::TestCase
+  def run_query(script, capi: false)
+    Dir.mktmpdir do |dir|
+      cmd = BitClust::Subcommands::QueryCommand.new
+      cmd.parse([script])
+      out = StringIO.new
+      orig, $stdout = $stdout, out
+      begin
+        cmd.exec([script], {:prefix => dir, :capi => capi})
+      ensure
+        $stdout = orig
+      end
+      out.string
+    end
+  end
+
+  def test_db_is_available_to_the_script
+    assert_equal %Q("BitClust::MethodDatabase"\n), run_query('@db.class.name')
+  end
+
+  def test_capi_uses_function_database
+    assert_equal %Q("BitClust::FunctionDatabase"\n), run_query('@db.class.name', capi: true)
+  end
+end

data/test/test_remote.rb

@@ -0,0 +1,374 @@
+# frozen_string_literal: true
+require 'test/unit'
+require 'tmpdir'
+require 'fileutils'
+require 'stringio'
+require 'json'
+require 'time'
+require 'bitclust'
+require 'bitclust/searcher'
+require 'bitclust/remote'
+
+# ローカル DB が無いときのリモート検索(docs.ruby-lang.org の検索索引
+# search_data.js と Markdown 配信をキャッシュ付きで使う)。
+#
+# テストリスト:
+# Cache:
+# [x] 未取得なら GET して保存し本文を返す
+# [x] 1 日以内のキャッシュはネットワークに行かずに返す
+# [x] 1 日以上古ければ If-Modified-Since 付きで確認し、304 なら touch して返す
+# [x] 200 なら上書き保存する
+# [x] 404 はキャッシュを消して nil
+# [x] 接続エラー時にキャッシュがあれば古くても返して stale にする。無ければ例外
+# [x] 本文は UTF-8 として扱う
+# Index:
+# [x] search_data.js を読んでクラス・メソッド(path から クラス・種別・名前)・ライブラリ・関数にする
+# [x] メソッド指定は refe と同じ規則(クラスは大小無視の前方一致→完全一致、種別は typemark)
+# [x] Kernel.#printf と Kernel?.printf は同じ module function。Kernel.printf は特異メソッドなので該当なし
+# [x] 種別なし 2 語は全種別から探す
+# [x] 3 語の種別は typemark として検査する(不正・$ は InvalidKey)
+# [x] $ 始まりは特殊変数
+# [x] A::B はクラス → 定数の順
+# [x] 大文字 1 語はクラス → メソッド名の順、小文字 1 語はメソッド名 → クラス → ライブラリ → 関数の順
+# [x] 語なしは全クラス、class_only: はクラスだけ
+# [x] document・heading は検索対象にしない
+# Remote#lookup:
+# [x] 1 件に決まれば .md を取得して本文と出典 URL を書く
+# [x] 複数なら名前一覧(line: なら 1 行 1 件、describe_all: なら全件の本文)
+# [x] 見つからなければメッセージと検索ページ URL
+# [x] 索引が取れずキャッシュも無ければメッセージだけ(例外にしない)
+# [x] Remote.default は BITCLUST_REMOTE_URL が指定があればその URL
+# [x] Remote.default は BITCLUST_REMOTE_URL が none(大小無視)か空なら nil(Windows では空の環境変数を作れない)
+class TestRemote < Test::Unit::TestCase
+  BASE_URL = 'https://docs.ruby-lang.org/ja/latest/'
+
+  INDEX = {
+    index: [
+      { name: 'String', full_name: 'String', type: 'class', path: 'class/String.html' },
+      { name: 'StringIO', full_name: 'StringIO', type: 'class', path: 'class/StringIO.html' },
+      { name: 'Kernel', full_name: 'Kernel', type: 'module', path: 'class/Kernel.html' },
+      { name: 'File', full_name: 'File', type: 'class', path: 'class/File.html' },
+      { name: 'File::Stat', full_name: 'File::Stat', type: 'class', path: 'class/File=3a=3aStat.html' },
+      { name: 'ARGF', full_name: 'ARGF', type: 'object', path: 'class/ARGF.html' },
+      { name: 'gsub', full_name: 'String#gsub', type: 'instance_method', path: 'method/String/i/gsub.html' },
+      { name: 'gsub!', full_name: 'String#gsub!', type: 'instance_method', path: 'method/String/i/gsub=21.html' },
+      { name: 'size', full_name: 'String#size', type: 'instance_method', path: 'method/String/i/size.html' },
+      { name: 'size', full_name: 'StringIO#size', type: 'instance_method', path: 'method/StringIO/i/size.html' },
+      { name: 'size', full_name: 'File#size', type: 'instance_method', path: 'method/File/i/size.html' },
+      { name: 'size', full_name: 'File.size', type: 'class_method', path: 'method/File/s/size.html', match_name: 'File::size' },
+      { name: 'new', full_name: 'String.new', type: 'class_method', path: 'method/String/s/new.html', match_name: 'String::new' },
+      { name: 'printf', full_name: 'Kernel?.printf', type: 'class_method', path: 'method/Kernel/m/printf.html', match_name: 'Kernel::#printf' },
+      { name: 'SEPARATOR', full_name: 'File::SEPARATOR', type: 'constant', path: 'method/File/c/SEPARATOR.html' },
+      { name: '$stdout', full_name: '$stdout', type: 'variable', path: 'method/Kernel/v/stdout.html' },
+      { name: 'json', full_name: 'json', type: 'library', path: 'library/json.html' },
+      { name: 'net/http', full_name: 'net/http', type: 'library', path: 'library/net=2fhttp.html' },
+      { name: 'rb_str_new', full_name: 'rb_str_new', type: 'function', path: 'function/rb_str_new.html' },
+      { name: 'ReFe', full_name: 'ReFe', type: 'document', path: 'doc/ReFe.html' },
+      { name: 'Zzz', full_name: 'Zzz (Ruby用語集)', type: 'heading', path: 'doc/glossary.html#Zzz' },
+    ],
+  }.freeze
+  INDEX_JS = "var search_data = #{JSON.generate(INDEX)};\n"
+
+  PAGES = {
+    'js/search_data.js' => INDEX_JS,
+    'method/String/i/gsub.md' => "# String#gsub\n\n### def gsub(pattern, replace) -> String\n\n置き換えます。\n",
+    'method/String/i/size.md' => "# String#size\n\n長さです。\n",
+    'method/File/s/size.md' => "# File.size\n\nサイズです。\n",
+    'method/File/i/size.md' => "# File#size\n\nサイズです。\n",
+    'method/StringIO/i/size.md' => "# StringIO#size\n\nサイズです。\n",
+    'class/String.md' => "# class String < Object\n\n文字列のクラスです。\n",
+    'library/json.md' => "# library json\n\nJSON です。\n",
+  }.freeze
+
+  T0 = Time.utc(2026, 9, 2, 12, 0, 0)
+
+  def setup
+    @dir = Dir.mktmpdir
+    @saved_env = ENV['BITCLUST_REMOTE_URL']
+    ENV.delete('BITCLUST_REMOTE_URL')
+  end
+
+  def teardown
+    FileUtils.rm_rf(@dir)
+    @saved_env ? ENV['BITCLUST_REMOTE_URL'] = @saved_env : ENV.delete('BITCLUST_REMOTE_URL')
+  end
+
+  # pages: base_url からの相対パス => 本文。無いパスは 404。requests に
+  # [URL, ヘッダ] を記録する
+  def fake_fetcher(pages = PAGES, requests = [])
+    lambda do |uri, headers|
+      requests << [uri.to_s, headers]
+      rel = uri.to_s.delete_prefix(BASE_URL)
+      pages.key?(rel) ? [200, pages[rel].dup] : [404, '<Error><Code>AccessDenied</Code></Error>']
+    end
+  end
+
+  def remote(pages = PAGES, requests = [], now: T0)
+    BitClust::Remote.new(base_url: BASE_URL, fetcher: fake_fetcher(pages, requests),
+                         cache_dir: @dir, clock: -> { now })
+  end
+
+  def index
+    BitClust::Remote::Index.parse(INDEX_JS)
+  end
+
+  def names(entries)
+    entries.map(&:full_name)
+  end
+
+  def cache(fetcher, now: T0)
+    BitClust::Remote::Cache.new(dir: @dir, fetcher: fetcher, clock: -> { now })
+  end
+
+  def gsub_uri
+    URI("#{BASE_URL}method/String/i/gsub.md")
+  end
+
+  # --- Cache ---
+
+  def test_cache_fetches_and_stores
+    requests = []
+    hit = cache(fake_fetcher(PAGES, requests)).fetch(gsub_uri)
+    assert_match(/置き換えます。/, hit.body)
+    assert_false(hit.stale)
+    assert_equal([[gsub_uri.to_s, {}]], requests)
+    path = File.join(@dir, 'docs.ruby-lang.org', 'ja', 'latest', 'method', 'String', 'i', 'gsub.md')
+    assert_equal(PAGES['method/String/i/gsub.md'], File.read(path, encoding: 'UTF-8'))
+    assert_equal(T0, File.mtime(path))
+  end
+
+  def test_cache_reuses_fresh_copy_without_network
+    requests = []
+    c = cache(fake_fetcher(PAGES, requests))
+    c.fetch(gsub_uri)
+    later = cache(fake_fetcher(PAGES, requests), now: T0 + 23 * 3600)
+    hit = later.fetch(gsub_uri)
+    assert_match(/置き換えます。/, hit.body)
+    assert_equal(1, requests.size)
+  end
+
+  def test_cache_revalidates_old_copy_with_if_modified_since
+    requests = []
+    cache(fake_fetcher(PAGES, requests)).fetch(gsub_uri)
+    not_modified = lambda do |uri, headers|
+      requests << [uri.to_s, headers]
+      [304, '']
+    end
+    now = T0 + 25 * 3600
+    hit = cache(not_modified, now: now).fetch(gsub_uri)
+    assert_match(/置き換えます。/, hit.body)
+    assert_false(hit.stale)
+    assert_equal(2, requests.size)
+    assert_equal({ 'If-Modified-Since' => T0.httpdate }, requests.last[1])
+    assert_equal(now, File.mtime(hit.path))
+  end
+
+  def test_cache_overwrites_on_200
+    cache(fake_fetcher(PAGES)).fetch(gsub_uri)
+    updated = PAGES.merge('method/String/i/gsub.md' => "# String#gsub\n\n新しい説明。\n")
+    hit = cache(fake_fetcher(updated), now: T0 + 2 * 86400).fetch(gsub_uri)
+    assert_match(/新しい説明。/, hit.body)
+    assert_equal("# String#gsub\n\n新しい説明。\n", File.read(hit.path, encoding: 'UTF-8'))
+  end
+
+  def test_cache_removes_copy_on_404
+    c = cache(fake_fetcher(PAGES))
+    hit = c.fetch(gsub_uri)
+    assert_nil(cache(fake_fetcher({}), now: T0 + 2 * 86400).fetch(gsub_uri))
+    assert_false(File.exist?(hit.path))
+    assert_nil(cache(fake_fetcher({})).fetch(URI("#{BASE_URL}class/Nope.md")))
+  end
+
+  def test_cache_serves_stale_copy_when_offline
+    failing = ->(_uri, _headers) { raise SocketError, 'getaddrinfo failed' }
+    assert_raise(SocketError) { cache(failing).fetch(gsub_uri) }
+    cache(fake_fetcher(PAGES)).fetch(gsub_uri)
+    hit = cache(failing, now: T0 + 2 * 86400).fetch(gsub_uri)
+    assert_match(/置き換えます。/, hit.body)
+    assert_true(hit.stale)
+  end
+
+  def test_cache_body_is_utf8
+    binary = { 'class/String.md' => "# class String < Object\n\n文字列のクラスです。\n".b }
+    hit = cache(fake_fetcher(binary)).fetch(URI("#{BASE_URL}class/String.md"))
+    assert_equal(Encoding::UTF_8, hit.body.encoding)
+    assert_true(hit.body.valid_encoding?)
+    again = cache(fake_fetcher({})).fetch(URI("#{BASE_URL}class/String.md"))
+    assert_equal(Encoding::UTF_8, again.body.encoding)
+    assert_match(/文字列のクラスです。/, again.body)
+  end
+
+  # --- Index ---
+
+  def test_index_parses_entries
+    i = index
+    e = i.search(%w[String#gsub]).first
+    assert_equal(['String', 'i', 'gsub', 'method/String/i/gsub.html'], [e.klass, e.typechar, e.name, e.path])
+    assert_equal(%w[File.size], names(i.search(%w[File.size])))
+    assert_equal(%w[net/http], names(i.search(%w[net/http])))
+  end
+
+  def test_index_method_spec_follows_refe_rules
+    i = index
+    assert_equal(%w[String#gsub], names(i.search(%w[String#gsub])))
+    assert_equal(%w[String#gsub], names(i.search(%w[str#gsub])))
+    assert_equal(%w[String#gsub String#gsub!], names(i.search(%w[Str#gs])))
+    assert_equal(%w[String#gsub!], names(i.search(%w[String#gsub!])))
+    assert_equal(%w[String.new], names(i.search(%w[String.new])))
+    assert_equal(%w[String#gsub], names(i.search(%w[String,gsub])))
+    assert_equal([], names(i.search(%w[String#nope])))
+    assert_equal([], names(i.search(%w[Nope#gsub])))
+  end
+
+  def test_index_module_function_typemarks
+    i = index
+    assert_equal(%w[Kernel?.printf], names(i.search(%w[Kernel.#printf])))
+    assert_equal(%w[Kernel?.printf], names(i.search(%w[Kernel?.printf])))
+    assert_equal([], names(i.search(%w[Kernel.printf])))
+  end
+
+  def test_index_two_words_search_all_types
+    i = index
+    assert_equal(%w[File#size File.size], names(i.search(%w[File size])))
+    assert_equal(%w[String#size StringIO#size], names(i.search(%w[str size])))
+    assert_equal([], names(i.search(%w[String nope])))
+  end
+
+  def test_index_three_words_check_typemark
+    i = index
+    assert_equal(%w[File.size], names(i.search(%w[File . size])))
+    assert_equal(%w[File#size], names(i.search(%w[File # size])))
+    assert_raise(BitClust::InvalidKey) { i.search(%w[File x size]) }
+    assert_raise(BitClust::InvalidKey) { i.search(%w[Kernel $ stdout]) }
+    assert_raise(BitClust::InvalidKey) { i.search(%w[a b c d]) }
+  end
+
+  def test_index_special_variable
+    i = index
+    assert_equal(%w[$stdout], names(i.search(%w[$stdout])))
+    assert_equal(%w[$stdout], names(i.search(%w[$std])))
+    assert_equal([], names(i.search(%w[$nope])))
+  end
+
+  def test_index_scoped_name_prefers_class_then_constant
+    i = index
+    assert_equal(%w[File::Stat], names(i.search(%w[File::Stat])))
+    assert_equal(%w[File::SEPARATOR], names(i.search(%w[File::SEPARATOR])))
+    assert_equal([], names(i.search(%w[File::NOPE])))
+  end
+
+  def test_index_single_word_order
+    i = index
+    assert_equal(%w[String], names(i.search(%w[String])))
+    assert_equal(%w[String StringIO], names(i.search(%w[S])))
+    assert_equal(%w[File#size File.size String#size StringIO#size], names(i.search(%w[size])).sort)
+    assert_equal(%w[Kernel?.printf], names(i.search(%w[printf])))
+    assert_equal(%w[json], names(i.search(%w[json])))
+    assert_equal(%w[rb_str_new], names(i.search(%w[rb_str_new])))
+    assert_equal(%w[ARGF], names(i.search(%w[argf])))
+    assert_equal([], names(i.search(%w[nothing])))
+  end
+
+  def test_index_no_words_and_class_only
+    i = index
+    assert_equal(%w[ARGF File File::Stat Kernel String StringIO], names(i.search([])).sort)
+    assert_equal(%w[String StringIO], names(i.search(%w[S], class_only: true)))
+    assert_equal([], names(i.search(%w[size], class_only: true)))
+    assert_raise(BitClust::InvalidKey) { i.search(%w[a b], class_only: true) }
+  end
+
+  def test_index_ignores_documents_and_headings
+    i = index
+    assert_equal([], names(i.search(%w[ReFe])))
+    assert_equal([], names(i.search(%w[Zzz])))
+  end
+
+  # --- Remote#lookup ---
+
+  def test_lookup_single_hit_shows_page_with_source_url
+    requests = []
+    out = StringIO.new
+    assert_true(remote(PAGES, requests).lookup(%w[String#gsub], out))
+    assert_match(/\A# String#gsub$/, out.string)
+    assert_match(/置き換えます。/, out.string)
+    assert_match(%r{^https://docs.ruby-lang.org/ja/latest/method/String/i/gsub.html$}, out.string)
+    assert_equal(["#{BASE_URL}js/search_data.js", "#{BASE_URL}method/String/i/gsub.md"], requests.map(&:first))
+  end
+
+  def test_lookup_multiple_hits_lists_names
+    out = StringIO.new
+    assert_true(remote.lookup(%w[size], out))
+    assert_equal("File#size File.size String#size StringIO#size \n", out.string)
+    out = StringIO.new
+    remote.lookup(%w[size], out, line: true)
+    assert_equal("File#size\nFile.size\nString#size\nStringIO#size\n", out.string)
+    out = StringIO.new
+    remote.lookup(%w[size], out, describe_all: true)
+    assert_match(/# File#size.*# File\.size.*# String#size.*# StringIO#size/m, out.string)
+  end
+
+  def test_lookup_single_hit_with_line_prints_name_only
+    out = StringIO.new
+    remote.lookup(%w[String#gsub], out, line: true)
+    assert_equal("String#gsub\n", out.string)
+  end
+
+  def test_lookup_class_only
+    out = StringIO.new
+    remote.lookup(%w[String], out, class_only: true)
+    assert_match(/文字列のクラスです。/, out.string)
+  end
+
+  def test_lookup_not_found_shows_search_url
+    out = StringIO.new
+    assert_nothing_raised do
+      assert_false(remote.lookup(%w[NoSuchClass#nope], out))
+    end
+    assert_match(/no such method: NoSuchClass#nope/, out.string)
+    assert_match(%r{https://docs.ruby-lang.org/ja/search/\?q=NoSuchClass%23nope}, out.string)
+    out = StringIO.new
+    assert_false(remote.lookup(%w[Nope], out, class_only: true))
+    assert_match(/no such class: Nope/, out.string)
+  end
+
+  def test_lookup_without_index_reports_instead_of_raising
+    failing = BitClust::Remote.new(base_url: BASE_URL, cache_dir: @dir, clock: -> { T0 },
+                                   fetcher: ->(_uri, _headers) { raise SocketError, 'getaddrinfo failed' })
+    out = StringIO.new
+    assert_nothing_raised do
+      assert_false(failing.lookup(%w[String#gsub], out))
+    end
+    assert_match(/docs\.ruby-lang\.org/, out.string)
+    assert_match(/getaddrinfo/, out.string)
+    assert_match(/bitclust setup/, out.string)
+  end
+
+  def test_lookup_uses_cached_index_when_offline
+    remote.lookup(%w[String#gsub], StringIO.new)
+    failing = BitClust::Remote.new(base_url: BASE_URL, cache_dir: @dir, clock: -> { T0 + 3 * 86400 },
+                                   fetcher: ->(_uri, _headers) { raise SocketError, 'getaddrinfo failed' })
+    out = StringIO.new
+    assert_true(failing.lookup(%w[String#gsub], out))
+    assert_match(/置き換えます。/, out.string)
+    assert_match(/オフライン/, out.string)
+  end
+
+  def test_default_follows_environment
+    assert_equal(BitClust::Remote::DEFAULT_BASE_URL, BitClust::Remote.default.base_url)
+    ENV['BITCLUST_REMOTE_URL'] = 'http://localhost:10080/ja/latest'
+    assert_equal('http://localhost:10080/ja/latest/', BitClust::Remote.default.base_url)
+  end
+
+  # Windows のシェル(cmd.exe・PowerShell)では空の環境変数を作れないので、
+  # 無効化は "none" でもできる
+  def test_default_is_disabled_by_none_or_empty
+    %w[none NONE None].each do |value|
+      ENV['BITCLUST_REMOTE_URL'] = value
+      assert_nil(BitClust::Remote.default, value)
+    end
+    ENV['BITCLUST_REMOTE_URL'] = ''
+    assert_nil(BitClust::Remote.default)
+    ENV['BITCLUST_REMOTE_URL'] = 'http://none.example/'
+    assert_equal('http://none.example/', BitClust::Remote.default.base_url)
+  end
+end