bitclust-core 1.6.0 → 1.7.0

data/test/test_markdown_exporter.rb

@@ -0,0 +1,260 @@
+# frozen_string_literal: true
+
+require 'test/unit'
+require 'stringio'
+require 'bitclust'
+require 'bitclust/markdown_exporter'
+require 'bitclust/mdparser'
+require 'bitclust/methoddatabase'
+require 'bitclust/functiondatabase'
+require 'bitclust/subcommands/statichtml_command'
+
+# MarkdownExporter: statichtml --markdown-output 用に、HTML の各ページと
+# 対になる Markdown を前処理済みソースから組み立てる。
+class TestMarkdownExporter < Test::Unit::TestCase
+  PARAMS = { "version" => "3.4" }
+
+  def setup
+    @urlmapper = BitClust::Subcommands::StatichtmlCommand::URLMapperEx.new(
+      :suffix => '.html',
+      :fs_casesensitive => true
+    )
+    @urlmapper.bitclust_html_base = '..'
+    @exporter = BitClust::MarkdownExporter.new(@urlmapper, '.html')
+  end
+
+  def parse_md(md, libname = "_builtin")
+    db = BitClust::MethodDatabase.dummy(PARAMS)
+    lib = BitClust::MDParser.new(db).parse(StringIO.new(md), libname, PARAMS)
+    [db, lib]
+  end
+
+  sub_test_case("convert_text") do
+    def test_bare_method_ref
+      assert_equal "[Array#index](../method/Array/i/index.md) を参照",
+                   @exporter.convert_text("[m:Array#index] を参照")
+    end
+
+    def test_bare_class_ref
+      assert_equal "[String](../class/String.md)",
+                   @exporter.convert_text("[c:String]")
+    end
+
+    def test_bare_library_ref
+      assert_equal "[csv](../library/csv.md)",
+                   @exporter.convert_text("[lib:csv]")
+    end
+
+    def test_bare_doc_ref
+      assert_equal "[spec/literal](../doc/spec=2fliteral.md)",
+                   @exporter.convert_text("[d:spec/literal]")
+    end
+
+    def test_bare_function_ref
+      assert_equal "[rb_ary_new](../function/rb_ary_new.md)",
+                   @exporter.convert_text("[f:rb_ary_new]")
+    end
+
+    def test_module_function_ref
+      # md 表記の ?. は内部表記 .# に正規化して URL を引く(ラベルは書かれたまま)
+      assert_equal "[Kernel?.puts](../method/Kernel/m/puts.md)",
+                   @exporter.convert_text("[m:Kernel?.puts]")
+    end
+
+    def test_method_ref_with_escaped_brackets
+      # [m:Array#\[\]] のようにエスケープされた参照。URL はエスケープを解いた
+      # メソッド名から引き、ラベルは書かれたまま(md として正しい形)を保つ
+      assert_equal "[Array#\\[\\]](../method/Array/i/=5b=5d.md)",
+                   @exporter.convert_text("[m:Array#\\[\\]]")
+    end
+
+    def test_labeled_ref
+      assert_equal "[個数](../method/Array/i/size.md)",
+                   @exporter.convert_text("[個数](m:Array#size)")
+    end
+
+    def test_labeled_ref_with_code_span_label
+      assert_equal "[`Array#size`](../method/Array/i/size.md)",
+                   @exporter.convert_text("[`Array#size`](m:Array#size)")
+    end
+
+    def test_markdown_link_kept
+      assert_equal "[Ruby](https://www.ruby-lang.org/)",
+                   @exporter.convert_text("[Ruby](https://www.ruby-lang.org/)")
+    end
+
+    def test_anchor_link_kept
+      assert_equal "[前述の例](#example)",
+                   @exporter.convert_text("[前述の例](#example)")
+    end
+
+    def test_url_ref
+      assert_equal "[https://www.ruby-lang.org/](https://www.ruby-lang.org/)",
+                   @exporter.convert_text("[url:https://www.ruby-lang.org/]")
+    end
+
+    def test_ref_in_page
+      assert_equal "[overview](#overview)",
+                   @exporter.convert_text("[ref:overview]")
+    end
+
+    def test_ref_cross_page
+      assert_equal "[spec/literal#num](../doc/spec=2fliteral.md#num)",
+                   @exporter.convert_text("[ref:d:spec/literal#num]")
+    end
+
+    def test_code_span_is_not_converted
+      assert_equal "`[m:Array#index]`",
+                   @exporter.convert_text("`[m:Array#index]`")
+    end
+
+    def test_code_fence_is_not_converted
+      src = "```ruby\n# [m:Array#index]\n```\n[m:Array#index]\n"
+      expected = "```ruby\n# [m:Array#index]\n```\n[Array#index](../method/Array/i/index.md)\n"
+      assert_equal expected, @exporter.convert_text(src)
+    end
+
+    def test_unknown_ref_type_is_kept
+      assert_equal "[man:printf(3)]", @exporter.convert_text("[man:printf(3)]")
+    end
+
+    def test_unresolvable_method_spec_is_kept
+      # クラス名とメソッド名に分割できない指定はそのまま残す
+      assert_equal "[m:broken spec]", @exporter.convert_text("[m:broken spec]")
+    end
+
+    def test_escaped_bracket_is_kept
+      assert_equal "\\[m:Array#index]", @exporter.convert_text("\\[m:Array#index]")
+    end
+  end
+
+  sub_test_case("pages") do
+    CLASS_MD = <<~MD
+      ---
+      library: _builtin
+      ---
+      # class Array < Object
+
+      配列クラス。[c:Enumerable] も参照。
+
+      ## Class Methods
+
+      ### def self.new(size) -> Array
+
+      生成。
+
+      ## Instance Methods
+
+      ### def index(val) -> Integer
+      ### def find_index(val) -> Integer
+
+      位置を返します。
+    MD
+
+    def test_class_page
+      _, lib = parse_md(CLASS_MD)
+      md = @exporter.class_page(lib.classes.first)
+      assert_equal <<~MD, md
+        # class Array < Object
+
+        配列クラス。[Enumerable](../class/Enumerable.md) も参照。
+
+        ## Class Methods
+
+        - [new](../method/Array/s/new.md)
+
+        ## Instance Methods
+
+        - [find_index](../method/Array/i/find_index.md)
+        - [index](../method/Array/i/index.md)
+      MD
+    end
+
+    def test_module_page_heading
+      md = <<~MD
+        ---
+        library: _builtin
+        ---
+        # module Comparable
+
+        比較。
+      MD
+      _, lib = parse_md(md)
+      page = @exporter.class_page(lib.classes.first)
+      assert page.start_with?("# module Comparable\n"), page
+    end
+
+    def test_method_page
+      _, lib = parse_md(CLASS_MD)
+      entry = lib.classes.first.entries.find { |e| e.names.include?("index") }
+      @urlmapper.bitclust_html_base = '../../..'
+      md = @exporter.method_page("Array#index", [entry])
+      assert_equal <<~MD, md
+        # Array#index
+
+        ### def index(val) -> Integer
+        ### def find_index(val) -> Integer
+
+        位置を返します。
+      MD
+    end
+
+    def test_method_page_normalizes_module_function_name
+      _, lib = parse_md(CLASS_MD)
+      entry = lib.classes.first.entries.first
+      md = @exporter.method_page("Kernel.#puts", [entry])
+      assert md.start_with?("# Kernel?.puts\n"), md
+    end
+
+    def test_library_page
+      md = <<~MD
+        ---
+        type: library
+        category: FileFormat
+        ---
+        CSV を扱うライブラリです。
+      MD
+      _, lib = parse_md(md, "csv")
+      page = @exporter.library_page(lib)
+      assert_equal <<~MD, page
+        # library csv
+
+        CSV を扱うライブラリです。
+      MD
+    end
+
+    def test_doc_page
+      db = BitClust::MethodDatabase.dummy(PARAMS)
+      entry = BitClust::DocEntry.new(db, "help")
+      entry.title = "ヘルプ"
+      entry.source = "\n[c:String] を参照。\n"
+      page = @exporter.doc_page(entry)
+      assert_equal <<~MD, page
+        # ヘルプ
+
+        [String](../class/String.md) を参照。
+      MD
+    end
+
+    def test_function_page
+      require 'bitclust/functiondatabase'
+      md = <<~MD
+        ### VALUE rb_ary_new()
+
+        空の配列を返します。
+      MD
+      db = BitClust::FunctionDatabase.dummy(PARAMS)
+      io = StringIO.new(md)
+      def io.path = "array.c.md"
+      BitClust::MDFunctionParser.new(db).parse(io, "array.c", PARAMS)
+      page = @exporter.function_page(db.functions.first)
+      assert_equal <<~MD, page
+        # rb_ary_new
+
+        ### VALUE rb_ary_new()
+
+        空の配列を返します。
+      MD
+    end
+  end
+end

data/test/test_mdcompiler.rb

@@ -23,7 +23,7 @@ class TestMDCompiler < Test::Unit::TestCase
     @rd = BitClust::RDCompiler.new(@u, 1, { :database => @db })
   end
 
-  def compile_method(compiler, src)
+  def compile_method(compiler, src, rbs_signature_overloads: nil)
     method_entry = Object.new
     mock(method_entry).source { src }
     mock(method_entry).index_id.any_times { "dummy" }
@@ -32,6 +32,7 @@ class TestMDCompiler < Test::Unit::TestCase
     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 { rbs_signature_overloads }
     compiler.compile_method(method_entry)
   end
 
@@ -58,6 +59,47 @@ class TestMDCompiler < Test::Unit::TestCase
 
   # ---- メソッドエントリ ----
 
+  # RBS シグネチャ表示: MDCompiler も entry_chunk をオーバーライドしている
+  # ので、rd 経路と同じ位置(説明 <dd> の直前)に同じ <dt> が出ること
+  def test_rbs_signatures_dt_matches_rd_output
+    rd_src = "--- index(val) -> Integer\n\n説明\n"
+    overloads = [{'segments' => [['t', '() -> void']]}]
+    md_src = BitClust::RRDToMarkdown.convert(rd_src)
+    rd_html = compile_method(@rd, rd_src, rbs_signature_overloads: overloads)
+    md_html = compile_method(@md, md_src, rbs_signature_overloads: overloads)
+    assert_include md_html,
+      '<dt class="rbs-signature"><code>() &rarr; void</code></dt>'
+    assert_equal rd_html, md_html
+  end
+
+  # チャンク振り分けは md 側のシグネチャ行(### def ...)でも rd と同じに
+  # 動くこと(MDCompiler は行を "--- " に正規化してから照合する)
+  def test_rbs_signatures_chunk_assignment_matches_rd_output
+    rd_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'},
+    ]
+    md_src = BitClust::RRDToMarkdown.convert(rd_src)
+    rd_html = compile_method(@rd, rd_src, rbs_signature_overloads: overloads)
+    md_html = compile_method(@md, md_src, rbs_signature_overloads: overloads)
+    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,
+      md_html)
+    assert_equal 2, md_html.scan('rbs-signature').size
+    assert_equal rd_html, md_html
+  end
+
   def test_method_signature_and_paragraph
     assert_equivalent_method <<~RD
       --- index(val) -> Integer
@@ -752,10 +794,10 @@ class TestMDCompiler < Test::Unit::TestCase
   def test_gfm_table_alignment
     md = "# T\n\n| a | b | c |\n|:--|:-:|--:|\n| 1 | 2 | 3 |\n"
     html = gfm_compiler.compile(md)
-    assert_include html, '<th align="left">a</th>'
-    assert_include html, '<th align="center">b</th>'
-    assert_include html, '<th align="right">c</th>'
-    assert_include html, '<td align="right">3</td>'
+    assert_include html, '<th style="text-align:left">a</th>'
+    assert_include html, '<th style="text-align:center">b</th>'
+    assert_include html, '<th style="text-align:right">c</th>'
+    assert_include html, '<td style="text-align:right">3</td>'
   end
 
   def test_gfm_pipe_line_without_delimiter_is_paragraph

data/test/test_mdparser.rb

@@ -82,7 +82,7 @@ class TestMDParser < Test::Unit::TestCase
 
       ## Class Methods
 
-      ### def new -> Comparable
+      ### def Comparable.new -> Comparable
 
       生成。
     MD
@@ -181,7 +181,7 @@ class TestMDParser < Test::Unit::TestCase
   end
 
   def test_unsupported_signature_forms_are_rejected
-    # RBS 形式（MARKUP_SPEC §3.2 で構想）と self. プレフィクスは描画側
+    # RBS 形式（MARKUP_SPEC §3.2 で構想）は描画側
     # （MethodSignature.parse）が受理できないため、パース時に拒否する
     base = <<~MD
       ---
@@ -197,12 +197,83 @@ class TestMDParser < Test::Unit::TestCase
 
       説明。
     MD
-    ['### def each: () { (untyped) -> void } -> self',
-     '### def self.new(size = 0) -> Foo'].each do |sig|
+    ['### def each: () { (untyped) -> void } -> self'].each do |sig|
       assert_raise(BitClust::ParseError, sig) { parse_md(base % sig) }
     end
   end
 
+  def test_self_and_class_name_prefixed_signatures
+    # クラスメソッドは `def self.name` / `def Klass.name` 形式でも書ける。
+    # どちらも singleton method として登録され、名前にプレフィクスは含まない
+    md = <<~MD
+      ---
+      library: _builtin
+      ---
+      # class Foo < Object
+
+      テスト。
+
+      ## Class Methods
+
+      ### def self.build(x) -> Foo
+
+      self. 形式。
+
+      ### def Foo.create(x) -> Foo
+
+      Klass. 形式。
+    MD
+    _, lib = parse_md(md)
+    entries = lib.classes.first.entries
+    assert_equal [["build"], ["create"]], entries.map(&:names)
+    assert_equal [:singleton_method, :singleton_method], entries.map(&:type)
+    # source には書かれたままの md が入る
+    assert_include entries[0].source, "### def self.build(x) -> Foo"
+  end
+
+  def test_main_prefixed_signature_on_object_page
+    # object main のページでは main. プレフィクスで特異メソッドを書ける
+    # （main は fatal・ARGF.class と同様に文法上クラス名として扱われる）
+    md = <<~MD
+      ---
+      library: _builtin
+      ---
+      # object main
+
+      テスト。
+
+      ## Class Methods
+
+      ### def main.include(*modules) -> self
+
+      main. 形式。
+    MD
+    _, lib = parse_md(md)
+    entries = lib.classes.first.entries
+    assert_equal [["include"]], entries.map(&:names)
+    assert_equal [:singleton_method], entries.map(&:type)
+  end
+
+  def test_self_prefixed_signature_in_instance_methods_section_is_rejected
+    # self. は singleton 確定なので Instance Methods セクションとは矛盾する
+    md = <<~MD
+      ---
+      library: _builtin
+      ---
+      # class Foo < Object
+
+      テスト。
+
+      ## Instance Methods
+
+      ### def self.bar -> nil
+
+      矛盾。
+    MD
+    error = assert_raise(BitClust::ParseError) { parse_md(md) }
+    assert_include error.message, "signature crash"
+  end
+
   def test_library_file_with_category
     md = <<~MD
       ---
@@ -341,6 +412,41 @@ class TestMDParser < Test::Unit::TestCase
     end
   end
 
+  def test_update_by_markdowntree_parse_error_suggests_gem_update
+    # manual/ が新しい bitclust を必要とする記法を含むとき、古い gem では
+    # パースエラーになる。原因へたどり着けるよう gem 更新の案内を添える
+    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('mylib.md', "---\ntype: library\n---\nmylib。\n")
+      write.call('mylib/Foo.md', <<~MD)
+        ---
+        library: mylib
+        ---
+        # class Foo < Object
+
+        クラス。
+
+        ## Instance Methods
+
+        ### def bar: (Integer) -> String
+
+        RBS 形式のシグネチャ(未対応)。
+      MD
+
+      db = BitClust::MethodDatabase.dummy(PARAMS)
+      error = assert_raise(BitClust::ParseError) do
+        db.update_by_markdowntree(root)
+      end
+      assert_include error.message, "unsupported method signature"
+      assert_include error.message, "bitclust の gem を更新すると解決するかもしれません"
+    end
+  end
+
   def test_copy_doc_md_keeps_relative_location
     # Windows CI 対応: doc エントリの source_location は md_root と同じ形
     # （相対で渡せば相対 manual/doc/...）で格納する。絶対パス化すると
@@ -535,4 +641,113 @@ class TestMDParser < Test::Unit::TestCase
     assert_equal('2.0.0', entry.since_of('fuga'))
     assert_equal('3.0', entry.since_of('fuga2'))
   end
+
+  def test_entry_style_bare_def_in_singleton_section_is_rejected
+    # MARKUP_SPEC §3.1: 特異メソッドはプレフィクス必須（def 行だけで
+    # メソッド種別が分かるようにする）
+    md = <<~MD
+      ---
+      library: _builtin
+      ---
+      # class Foo < Object
+
+      テスト。
+
+      ## Class Methods
+
+      ### def build(x) -> Foo
+
+      プレフィクスなし。
+    MD
+    error = assert_raise(BitClust::ParseError) { parse_md(md) }
+    assert_include error.message, "singleton method entry must be written as `def Foo.name' or `def self.name'"
+  end
+
+  def test_entry_style_keyword_section_mismatch_is_rejected
+    # rurema/doctree#3291 型の分類間違い: キーワードとセクションの不一致
+    base = <<~MD
+      ---
+      library: _builtin
+      ---
+      # class Foo < Object
+
+      テスト。
+
+      ## %s
+
+      ### %s
+
+      不一致。
+    MD
+    [
+      # Class Methods 配下の const（#3291 の実例）
+      ['Class Methods', 'const CURRENT -> Foo', "entry keyword `const' does not match this section (expected `def')"],
+      # Constants 配下の gvar
+      ['Constants', 'gvar $foo -> Foo', "entry keyword `gvar' does not match this section (expected `const')"],
+      # Instance Methods 配下の const
+      ['Instance Methods', 'const BAR -> Integer', "entry keyword `const' does not match this section (expected `def')"],
+    ].each do |section, sig, message|
+      error = assert_raise(BitClust::ParseError, "#{section} / #{sig}") do
+        parse_md(base % [section, sig])
+      end
+      assert_include error.message, message
+    end
+  end
+
+  def test_entry_style_module_functions_require_keyword
+    md = <<~MD
+      ---
+      library: _builtin
+      ---
+      # module Foo
+
+      テスト。
+
+      ## Module Functions
+
+      ### def bar -> nil
+
+      module_function キーワードなし。
+    MD
+    error = assert_raise(BitClust::ParseError) { parse_md(md) }
+    assert_include error.message, "entry keyword `def' does not match this section (expected `module_function def')"
+  end
+
+  def test_entry_style_accepts_consistent_forms
+    md = <<~MD
+      ---
+      library: _builtin
+      ---
+      # class Foo < Object
+
+      テスト。
+
+      ## Class Methods
+
+      ### def Foo.build(x) -> Foo
+
+      Klass 形式。
+
+      ### def self.create(x) -> Foo
+
+      self 形式。
+
+      ## Instance Methods
+
+      ### def each {|x| ... } -> self
+
+      素の def。
+
+      ## Constants
+
+      ### const BAR -> Integer
+
+      定数。
+    MD
+    _, lib = parse_md(md)
+    entries = lib.classes.first.entries
+    assert_equal [["build"], ["create"], ["each"], ["BAR"]], entries.map(&:names)
+    assert_equal [:singleton_method, :singleton_method, :instance_method, :constant],
+                 entries.map(&:type)
+  end
 end