bitclust-core 1.6.0 → 1.7.0

data/test/test_rbssig_command.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+require 'test/unit'
+require 'bitclust'
+require 'bitclust/methoddatabase'
+require 'bitclust/subcommands/rbssig_command'
+require 'stringio'
+require 'tmpdir'
+require 'fileutils'
+require 'json'
+
+# rbssig サブコマンド(RBS シグネチャ表示)。
+#
+#   bitclust rbssig --sig-dir=DIR <dbpath>
+#   bitclust rbssig --sig-root=RBS_CHECKOUT <dbpath>
+#
+# RBS シグネチャは 4.0 以降のドキュメント専用なので、DB の version が
+# 4.0 未満ならエラーにする(比較は display_typemark と同じく Gem::Version。
+# 文字列比較だと "10.0" が "4.0" より小さく見える)。
+#
+# テストリスト:
+# [x] グローバル --database 不要(needs_database? が false)
+# [x] --sig-root/--sig-dir がどちらも無いとエラー
+# [x] dbpath がちょうど 1 個でないとエラー
+# [x] DB の version が 4.0 未満だとエラー
+# [x] version 10.0 は 4.0 以降として通る(Gem::Version 比較)
+# [x] 4.0 の DB に rbs_sig が書き込まれ、統計行が出力される
+# [x] --dry-run は統計だけ表示して実 DB には書き込まない
+# [x] --sig-root は core/ と stdlib/ を持つチェックアウトを読める
+# [x] Runner に登録されている(bitclust rbssig として呼べる)
+class TestRbssigCommand < Test::Unit::TestCase
+  def setup
+    @tmpdir = Dir.mktmpdir
+    @sig_dir = File.join(@tmpdir, 'sig')
+    FileUtils.mkdir_p(@sig_dir)
+    File.write(File.join(@sig_dir, 'foo.rbs'), <<~RBS)
+      class Foo
+        def bar: (Integer) -> String
+      end
+    RBS
+  end
+
+  def teardown
+    FileUtils.rm_rf(@tmpdir)
+  end
+
+  def test_needs_no_global_database_option
+    cmd = BitClust::Subcommands::RbssigCommand.new
+    assert_false cmd.needs_database?
+  end
+
+  def test_no_sig_source_is_an_error
+    db = build_db('4.0')
+    assert_command_error([db])
+  end
+
+  def test_requires_exactly_one_dbpath
+    db = build_db('4.0')
+    assert_command_error(["--sig-dir=#{@sig_dir}"])
+    assert_command_error(["--sig-dir=#{@sig_dir}", db, db])
+  end
+
+  def test_old_database_version_is_an_error
+    db = build_db('3.4')
+    assert_command_error(["--sig-dir=#{@sig_dir}", db])
+  end
+
+  def test_version_10_passes_the_gate
+    db = build_db('10.0')
+    out = run_command(["--sig-dir=#{@sig_dir}", db])
+    assert_match(/version 10\.0/, out)
+    assert_equal [['t', '('], ['c', 'Integer'], ['t', ') -> '], ['c', 'String']],
+                 find_entry(db, 'bar').rbs_signature_overloads[0]['segments']
+  end
+
+  def test_fills_rbs_sig_and_prints_stats
+    db = build_db('4.0')
+    out = run_command(["--sig-dir=#{@sig_dir}", db])
+    assert_equal '(Integer) -> String',
+                 find_entry(db, 'bar').rbs_signature_overloads[0]['segments'].map {|_k, t| t }.join
+    assert_nil find_entry(db, 'nope').rbs_signature_overloads
+    assert_match(
+      /\Adb-4\.0 \(version 4\.0\): entries_updated=1 sigs_matched=1 methods_missed=1\n\z/,
+      out)
+  end
+
+  def test_dry_run_leaves_database_untouched
+    db = build_db('4.0')
+    out = run_command(["--sig-dir=#{@sig_dir}", db, '--dry-run'])
+    assert_nil find_entry(db, 'bar').rbs_signature_overloads
+    assert_match(/entries_updated=1/, out)
+  end
+
+  def test_sig_root_reads_core_and_stdlib_layout
+    root = File.join(@tmpdir, 'rbs-checkout')
+    FileUtils.mkdir_p("#{root}/core")
+    File.write("#{root}/core/foo.rbs", <<~RBS)
+      class Foo
+        def bar: (String) -> Integer
+      end
+    RBS
+    # core_root を与えると rbs は stringio を暗黙に要求するので、
+    # 本物のチェックアウトと同じく stdlib/ も置く
+    FileUtils.mkdir_p("#{root}/stdlib/stringio/0")
+    File.write("#{root}/stdlib/stringio/0/stringio.rbs", "class StringIO\nend\n")
+
+    db = build_db('4.0')
+    run_command(["--sig-root=#{root}", db])
+    assert_equal '(String) -> Integer',
+                 find_entry(db, 'bar').rbs_signature_overloads[0]['segments'].map {|_k, t| t }.join
+  end
+
+  def test_registered_in_runner
+    require 'bitclust/runner'
+    runner = BitClust::Runner.new
+    runner.prepare
+    subcommands = runner.instance_variable_get(:@subcommands)
+    assert_kind_of BitClust::Subcommands::RbssigCommand, subcommands['rbssig']
+  end
+
+  private
+
+  def build_db(version)
+    root = "#{@tmpdir}/tree-#{version}/refm/api/src"
+    FileUtils.mkdir_p("#{root}/_builtin")
+    File.write("#{root}/LIBRARIES", "_builtin\n")
+    File.write("#{root}/_builtin.rd", <<~RD)
+      description
+
+      = class Foo < Object
+      == Instance Methods
+      --- bar(val) -> String
+
+      説明
+
+      --- nope -> nil
+
+      説明
+    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 find_entry(prefix, name)
+    db = BitClust::MethodDatabase.new(prefix)
+    db.get_class('Foo').entries.find {|m| m.name?(name) }
+  end
+
+  def run_command(argv)
+    cmd = BitClust::Subcommands::RbssigCommand.new
+    cmd.parse(argv)
+    out = StringIO.new
+    orig_stdout = $stdout
+    $stdout = out
+    begin
+      cmd.exec(argv, { prefix: nil, capi: false })
+    ensure
+      $stdout = orig_stdout
+    end
+    out.string
+  end
+
+  def assert_command_error(argv)
+    cmd = BitClust::Subcommands::RbssigCommand.new
+    cmd.parse(argv)
+    assert_raise(SystemExit) do
+      capture_stderr { cmd.exec(argv, { prefix: nil, capi: false }) }
+    end
+  end
+
+  def capture_stderr
+    orig = $stderr
+    $stderr = StringIO.new
+    yield
+  ensure
+    $stderr = orig
+  end
+end

data/test/test_rdcompiler.rb

@@ -28,9 +28,102 @@ class TestRDCompiler < Test::Unit::TestCase
     mock(method_entry).names.any_times{ names }
     mock(method_entry).since_map.any_times{ since_map }
     mock(method_entry).until_map.any_times{ until_map }
+    mock(method_entry).rbs_signature_overloads.any_times { nil }
     assert_equal(expected, @c.compile_method(method_entry))
   end
 
+  # RBS シグネチャ表示: rbs_sig property を持つエントリだけが、メソッド
+  # 見出しの <dt> 群の直後・説明 <dd> の直前に 1 オーバーロード 1 行の
+  # <dt class="rbs-signature"> を出す(dd だと説明の一部に見える。pre を
+  # 使うと script.js が COPY ボタンを付けてしまうので code のみ)。
+  # 型名セグメントは DB に存在するクラスだけリンク化し、テキストは
+  # エスケープした上で -> を &rarr; にする。
+  def test_method_with_rbs_signatures_renders_dt_lines
+    stub(@db).fetch_class('String') { :exists }
+    stub(@db).fetch_class('Integer') { raise BitClust::ClassNotFound, 'Integer' }
+    overloads = [
+      {'segments' => [['t', '('], ['c', 'Integer'], ['t', ') -> '], ['c', 'String']]},
+      {'segments' => [['t', '(String & Integer) -> void']]},
+    ]
+    method_entry = rbs_method_entry("--- index(val) -> Integer\n\n説明\n", overloads)
+
+    html = @c.compile_method(method_entry)
+    assert_include html,
+      %Q[(Integer) &rarr; <a href="dummy/class/String">String</a>]
+    assert_include html, '(String &amp; Integer) &rarr; void'
+    assert_match(
+      %r!</dt>\n(<dt class="rbs-signature"><code>.+</code></dt>\n){2}<dd class="method-description">!,
+      html)
+    assert_not_match(/<pre|<dd class="rbs-/, html)
+  end
+
+  # 引数パターンでチャンクが分かれるメソッド(Array.new 型)では、各
+  # オーバーロードが引数名・アリティ・ブロック有無で最も近いチャンクの
+  # 見出し直下にだけ出る(全チャンクへの重複表示をしない)
+  def test_method_with_rbs_signatures_assigns_overloads_to_chunks
+    src = <<~RD
+      --- index(sub) -> Integer | nil
+
+      文字列で探す。
+
+      --- index(pattern) {|s| ... } -> Integer | nil
+
+      ブロックで探す。
+    RD
+    overloads = [
+      {'segments' => [['t', '(String sub) -> Integer?']],
+       'params' => ['sub'], 'arity' => [1, 1]},
+      {'segments' => [['t', '(Regexp pattern) { (String) -> bool } -> Integer?']],
+       'params' => ['pattern'], 'arity' => [1, 1], 'block' => 'req'},
+    ]
+    method_entry = rbs_method_entry(src, overloads)
+
+    html = @c.compile_method(method_entry)
+    assert_match(
+      %r!<code>index\(sub\).*?</dt>\n<dt class="rbs-signature"><code>\(String sub\) &rarr; Integer\?</code></dt>\n<dd!m,
+      html)
+    assert_match(
+      %r!<code>index\(pattern\).*?</dt>\n<dt class="rbs-signature"><code>\(Regexp pattern\) \{ \(String\) &rarr; bool \} &rarr; Integer\?</code></dt>\n<dd!m,
+      html)
+    assert_equal 2, html.scan('rbs-signature').size
+  end
+
+  # 旧形式の DB(メタ情報なし)ではチャンク振り分けができないので、
+  # 先頭チャンクにまとめて出す(重複はしない)
+  def test_method_with_rbs_signatures_without_meta_falls_back_to_first_chunk
+    src = <<~RD
+      --- index(sub) -> Integer | nil
+
+      文字列で探す。
+
+      --- index(pattern) {|s| ... } -> Integer | nil
+
+      ブロックで探す。
+    RD
+    overloads = [
+      {'segments' => [['t', '(String sub) -> Integer?']]},
+      {'segments' => [['t', '(Regexp pattern) { (String) -> bool } -> Integer?']]},
+    ]
+    html = @c.compile_method(rbs_method_entry(src, overloads))
+    assert_equal 2, html.scan('rbs-signature').size
+    assert_match(
+      %r!<code>index\(sub\).*?</dt>\n(<dt class="rbs-signature">.*\n){2}<dd!,
+      html)
+  end
+
+  def rbs_method_entry(src, overloads)
+    method_entry = Object.new
+    mock(method_entry).source { src }
+    mock(method_entry).index_id.any_times { 'dummy' }
+    mock(method_entry).defined?.any_times { true }
+    mock(method_entry).id.any_times { 'String/i.index._builtin' }
+    mock(method_entry).names.any_times { [] }
+    mock(method_entry).since_map.any_times { {} }
+    mock(method_entry).until_map.any_times { {} }
+    mock(method_entry).rbs_signature_overloads.any_times { overloads }
+    method_entry
+  end
+
   # badge のカタログ訳(「Ruby %s から」等)を検証するテストで使う、
   # 日本語カタログを読み込んだ compiler を作る(setup の @c はカタログ無しの
   # C ロケールなので、_() はキーそのまま(英語)を返してしまう)
@@ -230,6 +323,7 @@ HERE
     mock(method_entry).names.any_times { ['mf'] }
     mock(method_entry).since_map.any_times { {} }
     mock(method_entry).until_map.any_times { {} }
+    mock(method_entry).rbs_signature_overloads.any_times { nil }
     mock(method_entry).klass.any_times { klass }
     mock(method_entry).display_typemark.any_times { '?.' }
 
@@ -250,6 +344,7 @@ HERE
     mock(method_entry).names.any_times { ['mf'] }
     mock(method_entry).since_map.any_times { {} }
     mock(method_entry).until_map.any_times { {} }
+    mock(method_entry).rbs_signature_overloads.any_times { nil }
 
     html = @c.compile_method(method_entry)
     assert_include(html, '<code>mf</code>')
@@ -979,7 +1074,7 @@ HERE
 
   data("library root"    => ['[[lib:/]]',        '<a href="dummy/library/">ライブラリ一覧</a>'],
        "builtin library" => ['[[lib:_builtin]]', '<a href="dummy/library/_builtin">組み込みライブラリ</a>'],
-       "C API root"      => ['[[f:/]]',          '<a href="dummy/function/">関数一覧</a>'])
+       "C API root"      => ['[[f:/]]',          '<a href="dummy/function/">C API 関数一覧</a>'])
   def test_bracket_link_with_catalog(data)
     target, expected = data
     prefix = File.expand_path('../data/bitclust/catalog', __dir__)
@@ -1029,6 +1124,7 @@ HERE
     mock(method_entry).names.any_times { [] }
     mock(method_entry).since_map.any_times { {} }
     mock(method_entry).until_map.any_times { {} }
+    mock(method_entry).rbs_signature_overloads.any_times { nil }
     html = @c.compile_method(method_entry)
     assert_not_include(html, 'UNKNOWN_META_INFO')
     assert_not_include(html, '{:')
@@ -1052,6 +1148,7 @@ HERE
     mock(method_entry).names.any_times { [] }
     mock(method_entry).since_map.any_times { {} }
     mock(method_entry).until_map.any_times { {} }
+    mock(method_entry).rbs_signature_overloads.any_times { nil }
     html = @c.compile_method(method_entry)
     assert_not_include(html, '{:')
     assert_include(html, 'to_a2')
@@ -1074,6 +1171,7 @@ HERE
     mock(method_entry).names.any_times { [] }
     mock(method_entry).since_map.any_times { {} }
     mock(method_entry).until_map.any_times { {} }
+    mock(method_entry).rbs_signature_overloads.any_times { nil }
     html = @c.compile_method(method_entry)
     assert_not_include(html, '{:')
     assert_include(html, 'このメソッドは定義されていません。')

data/test/test_search_index_generator.rb

@@ -511,3 +511,84 @@ HERE
     end
   end
 end
+
+class TestSearchIndexSnippet < Test::Unit::TestCase
+  # 検索結果の説明文(snippet)。meta description と同じ entry.description
+  # (最初の説明段落のプレーンテキスト)を、空でないときだけ持たせる。
+  #
+  # テストリスト:
+  # [x] class/method/special variable の各エントリが snippet を持つ
+  # [x] 説明が空のエントリは snippet キー自体を持たない
+  # [x] merge は複数版で同一エントリのとき最新版の snippet を採用する
+  # [x] 最新版に無いページは収録されている最終版の snippet を保つ
+  def setup
+    @prefix = 'db_snip'
+    @base = 'tree_snip'
+    @root = "#{@base}/refm/api/src"
+    FileUtils.mkdir_p("#{@root}")
+    File.open("#{@root}/LIBRARIES", 'w+') { |f| f.puts '_builtin' }
+    File.open("#{@root}/_builtin.rd", 'w+') do |f|
+      f.puts <<'HERE'
+description
+
+= class Foo < Object
+クラスの説明。
+== Instance Methods
+--- foo
+
+メソッドの説明。
+--- undocumented
+= module Kernel
+== Special Variables
+--- $; -> String | nil
+
+区切り文字。
+HERE
+    end
+    @db = BitClust::MethodDatabase.new(@prefix)
+    @db.init
+    @db.transaction do
+      [%w[version 3.4], %w[encoding utf-8]].each { |k, v| @db.propset(k, v) }
+    end
+    @db.transaction { @db.update_by_stdlibtree(@root) }
+    @gen = BitClust::SearchIndexGenerator.new
+  end
+
+  def teardown
+    FileUtils.rm_r([@prefix, @base], :force => true)
+  end
+
+  def find_entry(index, full_name)
+    index.find { |e| e[:full_name] == full_name }
+  end
+
+  def test_snippet_carries_entry_description
+    index = @gen.build_index(@db)
+    assert_equal 'クラスの説明。', find_entry(index, 'Foo')[:snippet]
+    assert_equal 'メソッドの説明。', find_entry(index, 'Foo#foo')[:snippet]
+    assert_equal '区切り文字。', find_entry(index, '$;')[:snippet]
+  end
+
+  def test_snippet_is_omitted_when_description_is_empty
+    index = @gen.build_index(@db)
+    e = find_entry(index, 'Foo#undocumented')
+    assert_not_nil e
+    assert_false e.key?(:snippet)
+  end
+
+  def test_merge_takes_snippet_from_newest_version
+    old_e = { name: 'X', full_name: 'X', type: 'class', path: 'class/-x.html', snippet: '古い説明' }
+    new_e = { name: 'X', full_name: 'X', type: 'class', path: 'class/-x.html', snippet: '新しい説明' }
+    merged = BitClust::SearchIndexGenerator.merge([['3.4', [new_e]], ['3.3', [old_e]]])
+    assert_equal 1, merged.size
+    assert_equal '新しい説明', merged.first[:snippet]
+    assert_equal %w[3.3 3.4], merged.first[:versions]
+  end
+
+  def test_merge_keeps_snippet_of_last_version_having_the_page
+    only_old = { name: 'Y', full_name: 'Y', type: 'class', path: 'class/-y.html', snippet: '最終収録版の説明' }
+    merged = BitClust::SearchIndexGenerator.merge([['3.4', []], ['3.3', [only_old]]])
+    assert_equal '最終収録版の説明', merged.first[:snippet]
+    assert_equal %w[3.3], merged.first[:versions]
+  end
+end

data/test/test_setup_command.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+require 'test/unit'
+require 'bitclust'
+require 'bitclust/subcommands/setup_command'
+
+# setup サブコマンドの既定バージョン。
+#
+# テストリスト:
+# [x] 既定の対象バージョンに teeny が付いていない
+#     (#%if (version == "V") や #%version V の等値ゲートは文字列一致なので、
+#     teeny 付きの版名で DB を作ると doctree CI・生成済みドキュメントと
+#     ゲートの判定がずれる)
+class TestSetupCommand < Test::Unit::TestCase
+  def test_default_versions_have_no_teeny
+    versions = BitClust::Subcommands::SetupCommand.new.instance_variable_get(:@versions)
+    assert_false(versions.empty?)
+    versions.each do |version|
+      assert_match(/\A\d+\.\d+\z/, version)
+    end
+  end
+end

data/test/test_statichtml_command.rb

@@ -202,3 +202,140 @@ class TestStatichtmlSitemap < Test::Unit::TestCase
     end
   end
 end
+
+class TestStatichtmlMarkdownOutput < Test::Unit::TestCase
+  def build_command(markdown_output: true)
+    cmd = BitClust::Subcommands::StatichtmlCommand.new
+    argv = ["--fs-casesensitive"]
+    argv.unshift("--markdown-output") if markdown_output
+    cmd.parse(argv)
+    cmd.instance_variable_set(:@verbose, false)
+    cmd.send(:create_manager_config)
+    urlmapper = cmd.instance_variable_get(:@urlmapper)
+    urlmapper.bitclust_html_base = '..'
+    cmd.instance_variable_set(:@markdown_exporter,
+                              BitClust::MarkdownExporter.new(urlmapper, '.html'))
+    cmd
+  end
+
+  def markdown_db
+    db = BitClust::MethodDatabase.dummy({ "version" => "3.4" })
+    def db.properties = { 'source_format' => 'markdown' }
+    db
+  end
+
+  def test_option_defaults_to_false
+    cmd = BitClust::Subcommands::StatichtmlCommand.new
+    assert_false(cmd.instance_variable_get(:@markdown_output))
+  end
+
+  def test_option_is_parsed
+    cmd = BitClust::Subcommands::StatichtmlCommand.new
+    cmd.parse(["--markdown-output"])
+    assert_true(cmd.instance_variable_get(:@markdown_output))
+  end
+
+  def test_markdown_path_replaces_html_suffix
+    cmd = BitClust::Subcommands::StatichtmlCommand.new
+    assert_equal("out/class/ARGF.class.md",
+                 cmd.send(:markdown_path, Pathname.new("out/class/ARGF.class.html")).to_s)
+  end
+
+  def test_writes_md_next_to_html_for_markdown_db
+    Dir.mktmpdir do |dir|
+      cmd = build_command
+      db = markdown_db
+      entry = BitClust::DocEntry.new(db, "help")
+      entry.title = "ヘルプ"
+      entry.source = "\n[c:String] を参照。\n"
+      path = Pathname.new(dir) + "doc/help.html"
+      FileUtils.mkdir_p(path.dirname)
+      cmd.send(:create_markdown_file_p, entry, path, db)
+      md = File.read(File.join(dir, "doc", "help.md"))
+      assert_equal("# ヘルプ\n\n[String](../class/String.md) を参照。\n", md)
+    end
+  end
+
+  def test_skips_md_for_non_markdown_db
+    Dir.mktmpdir do |dir|
+      cmd = build_command
+      db = BitClust::MethodDatabase.dummy({ "version" => "3.4" })
+      def db.properties = {}
+      entry = BitClust::DocEntry.new(db, "help")
+      entry.title = "ヘルプ"
+      entry.source = "\n本文\n"
+      path = Pathname.new(dir) + "doc/help.html"
+      FileUtils.mkdir_p(path.dirname)
+      cmd.send(:create_markdown_file_p, entry, path, db)
+      assert_false(File.exist?(File.join(dir, "doc", "help.md")))
+    end
+  end
+
+  def test_warns_when_db_is_not_markdown
+    cmd = build_command
+    db = BitClust::MethodDatabase.dummy({ "version" => "3.4" })
+    def db.properties = {}
+    orig_stderr, $stderr = $stderr, StringIO.new
+    begin
+      cmd.send(:warn_markdown_output_skipped, db, "the method database")
+      assert_match(/--markdown-output is ignored/, $stderr.string)
+    ensure
+      $stderr = orig_stderr
+    end
+  end
+
+  def test_no_warning_without_option
+    cmd = build_command(markdown_output: false)
+    db = BitClust::MethodDatabase.dummy({ "version" => "3.4" })
+    def db.properties = {}
+    orig_stderr, $stderr = $stderr, StringIO.new
+    begin
+      cmd.send(:warn_markdown_output_skipped, db, "the method database")
+      assert_equal("", $stderr.string)
+    ensure
+      $stderr = orig_stderr
+    end
+  end
+end
+
+class TestStatichtmlVersionSwitcher < 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_version_switcher_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', 'version_switcher.js'), "// vs\n")
+      cmd = build_command(themedir, outputdir)
+      cmd.send(:copy_version_switcher_script)
+      assert_true(File.file?(File.join(outputdir, 'js', 'version_switcher.js')))
+    end
+  end
+
+  # An older themedir without the file must not abort the whole build.
+  def test_theme_without_version_switcher_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_version_switcher_script) }
+        assert_match(/version_switcher\.js not found/, $stderr.string)
+      ensure
+        $stderr = orig_stderr
+      end
+      assert_false(File.exist?(File.join(outputdir, 'js', 'version_switcher.js')))
+    end
+  end
+end

data/theme/default/js/run.js

@@ -134,6 +134,20 @@ function setupBlock(pre, runner) {
   }
   group.prepend(button)
 
+  // RUN の使い方と制限(ruby.wasm で動かないサンプルがあること等)を
+  // 説明するヘルプページの RUN 節への動線。リンク先はページごとに相対
+  // URL が変わるため、サーバー側が layout の meta で埋め込んだ値を使う
+  const helpUrl = document.querySelector('meta[name="rurema-run-help"]')?.content
+  if (helpUrl) {
+    const help = document.createElement('a')
+    help.className = 'highlight__help-link'
+    help.href = helpUrl
+    help.textContent = '?'
+    help.title = 'RUN ボタンのヘルプ'
+    help.setAttribute('aria-label', 'RUN ボタンのヘルプ')
+    group.append(help)
+  }
+
   let output
   let outputTextNode
   const ensureOutput = () => {

data/theme/default/js/search_init.js

@@ -112,7 +112,9 @@
           this.escapeHTML(typeClass) + '">' + this.formatType(r.type) + '</span>';
       }
       html += '</p>';
-      if (r.snippet) html += '<div class="search-snippet">' + r.snippet + '</div>';
+      // snippet はインデックス生成側が入れたプレーンテキスト
+      // (エントリの説明の最初の段落)。HTML として解釈させない
+      if (r.snippet) html += '<div class="search-snippet">' + this.escapeHTML(r.snippet) + '</div>';
       li.innerHTML = html;
       return li;
     };

data/theme/default/js/search_page.js

@@ -158,7 +158,13 @@
         html += '<span class="search-type search-type-' +
           this.escapeHTML(typeClass) + '">' + this.formatType(r.type) + '</span>';
       }
-      html += '</p><p class="search-versions">';
+      html += '</p>';
+      // snippet はインデックス生成側が入れたプレーンテキスト
+      // (エントリの説明の最初の段落)。HTML として解釈させない
+      if (r.snippet) {
+        html += '<div class="search-snippet">' + this.escapeHTML(r.snippet) + '</div>';
+      }
+      html += '<p class="search-versions">';
       for (var i = 0; i < versions.length; i++) {
         html += '<a href="' + this.escapeHTML(versionHref(versions[i], r.path)) +
           '">' + this.escapeHTML(versions[i]) + '</a>';