bitclust-core 1.6.0 → 1.7.0

data/lib/bitclust/search_index_generator.rb

@@ -114,6 +114,9 @@ module BitClust
           key = e.values_at(:name, :full_name, :type, :path)
           entry = (merged[key] ||= e.merge(versions: []))
           entry[:versions] << version
+          # 説明文は「最新版か、収録されている最終版」のものを採用する。
+          # 昇順走査なので後勝ちで上書きすればよい
+          entry[:snippet] = e[:snippet] if e[:snippet]
         end
       end
       merged.values
@@ -126,14 +129,29 @@ module BitClust
 
     private
 
+    # 検索結果に添える説明文。meta description と同じ entry.description
+    # (最初の説明段落のプレーンテキスト)を使い、空なら nil(キー自体を
+    # 持たせない)。プレーンテキストのまま格納し、HTML エスケープは
+    # 表示側(search_init.js / search_page.js)で行う
+    def entry_snippet(entry)
+      desc = entry.description
+      desc unless desc.nil? || desc.empty?
+    end
+
+    def with_snippet(hash, entry)
+      snippet = entry_snippet(entry)
+      hash[:snippet] = snippet if snippet
+      hash
+    end
+
     def class_entries(db)
       db.classes.sort.reject(&:dummy?).map do |c|
-        {
+        with_snippet({
           name:      c.name,
           full_name: c.name,
           type:      c.type.to_s,
           path:      "class/#{encode(c.name)}#{@suffix}",
-        }
+        }, c)
       end
     end
 
@@ -162,11 +180,11 @@ module BitClust
             # sigil is the only thing distinguishing it, so keep it in +name+
             # too (not just +full_name+) or a "$;"-style query can't match it.
             name = full_name = tmark + mname
-            result << { name: name, full_name: full_name, type: type, path: path }
+            result << with_snippet({ name: name, full_name: full_name, type: type, path: path }, entry)
           else
             name = mname
             full_name = cname + tmark + mname
-            item = { name: name, full_name: full_name, type: type, path: path } #: entry
+            item = with_snippet({ name: name, full_name: full_name, type: type, path: path }, entry) #: entry
             if tmark.include?('.')
               # bitclust#279: singleton methods (".") and module functions
               # (".#"/"?.") keep a literal "." in full_name for display, but
@@ -185,12 +203,12 @@ module BitClust
 
     def library_entries(db)
       db.libraries.sort.map do |lib|
-        {
+        with_snippet({
           name:      lib.name,
           full_name: lib.name,
           type:      'library',
           path:      "library/#{encode(lib.name)}#{@suffix}",
-        }
+        }, lib)
       end
     end
 
@@ -201,12 +219,12 @@ module BitClust
         # Prose pages are identified by a Japanese title, so index the title
         # (for human queries) together with the slug (for identifier queries).
         label = (title && !title.empty? && title != slug) ? "#{title} (#{slug})" : slug
-        {
+        with_snippet({
           name:      label,
           full_name: label,
           type:      'document',
           path:      "doc/#{encode(slug)}#{@suffix}",
-        }
+        }, doc)
       end
     end
 
@@ -272,12 +290,12 @@ module BitClust
 
     def function_entries(fdb)
       fdb.functions.sort.map do |func|
-        {
+        with_snippet({
           name:      func.name,
           full_name: func.name,
           type:      'function',
           path:      "function/#{func.name}#{@suffix}",
-        }
+        }, func)
       end
     end
 

data/lib/bitclust/searcher.rb

@@ -121,6 +121,14 @@ module BitClust
       @parser.help
     end
 
+    # irb プラグインなど組み込み利用向けの入口。argv のパターンを db から
+    # 検索し、結果を view(TerminalView)へ出力する。db が nil なら
+    # 既定の場所(~/.bitclust/config など)から探す
+    def run_query(db, argv, view)
+      @view = view
+      search_pattern db, argv
+    end
+
     private
 
     def server_mode_check(argv)
@@ -374,12 +382,14 @@ module BitClust
 
   class TerminalView
 
-    def initialize(compiler, opts)
+    # io を省略すると出力先は呼び出し時点の $stdout(従来挙動)
+    def initialize(compiler, opts, io: nil)
       @compiler = compiler
       @describe_all = opts[:describe_all]
       @line = opts[:line]
       @encoding = opts[:encoding]
       @database = nil
+      @io = io
     end
 
     attr_accessor :database
@@ -546,7 +556,7 @@ module BitClust
     end
 
     def puts(*args)
-      super(*args.collect {|arg| convert(arg)})
+      (@io || $stdout).puts(*args.collect {|arg| convert(arg)})
     end
 
     def convert(string)

data/lib/bitclust/subcommands/rbssig_command.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+#
+# bitclust/subcommands/rbssig_command.rb
+#
+# RBS 型シグネチャを DB のメソッドエントリに書き込む(rbs_sig property):
+#
+#   bitclust rbssig --sig-root=RBS_CHECKOUT <dbpath>
+#   bitclust rbssig --sig-dir=DIR [--sig-dir=DIR ...] <dbpath>
+#
+# DB 構築(update)後・statichtml 前に実行する(methodsince と同じ位置)。
+# --sig-root には対象 Ruby バージョンに同梱される rbs のチェックアウト
+# (core/ と stdlib/ を含む)を渡す。表示は 4.0 以降のドキュメント専用
+# なので、DB の version が 4.0 未満ならエラーにする。
+
+require 'bitclust'
+require 'bitclust/subcommand'
+require 'bitclust/rbs_sig_importer'
+require 'tmpdir'
+require 'fileutils'
+
+module BitClust
+  module Subcommands
+    class RbssigCommand < Subcommand
+      MINIMUM_VERSION = Gem::Version.new('4.0')
+
+      def initialize
+        super
+        @sig_root = nil
+        @sig_dirs = []
+        @dry_run = false
+        @parser.banner = "Usage: #{File.basename($0, '.*')} rbssig [options] <dbpath>"
+        @parser.on('--sig-root=PATH', 'ruby/rbs checkout containing core/ and stdlib/.') {|path|
+          @sig_root = path
+        }
+        @parser.on('--sig-dir=PATH', 'Directory of extra .rbs files (repeatable).') {|path|
+          @sig_dirs.push path
+        }
+        @parser.on('--dry-run', 'Compute and print stats without saving.') {
+          @dry_run = true
+        }
+      end
+
+      # DB パスは位置引数で受けるのでグローバル --database は不要
+      def needs_database?
+        false
+      end
+
+      def exec(argv, options)
+        error('no --sig-root or --sig-dir given') if @sig_root.nil? && @sig_dirs.empty?
+        error("wrong number of arguments (#{argv.size} for 1)") unless argv.size == 1
+        path = argv.first
+        version = check_version(path)
+
+        sig_root = @sig_root
+        importer = RbsSigImporter.new(
+          core_root: sig_root && File.join(sig_root, 'core'),
+          repository_root: sig_root && File.join(sig_root, 'stdlib'),
+          sig_dirs: @sig_dirs)
+        stats =
+          if @dry_run
+            apply_dry_run(importer, path)
+          else
+            importer.apply(MethodDatabase.new(path))
+          end
+        puts "#{File.basename(path)} (version #{version}): " \
+             "entries_updated=#{stats[:entries_updated]} sigs_matched=#{stats[:sigs_matched]} " \
+             "methods_missed=#{stats[:methods_missed]}"
+      end
+
+      private
+
+      # RBS シグネチャ表示は 4.0 以降のドキュメント専用。比較は
+      # display_typemark(nameutils.rb)と同じく Gem::Version で行う
+      # (文字列比較だと "10.0" が "4.0" より小さく見える)
+      def check_version(path)
+        version = MethodDatabase.new(path).propget('version') or
+          error("#{path}: no version property (not a bitclust database?)")
+        begin
+          if Gem::Version.new(version) < MINIMUM_VERSION
+            error("#{path}: version #{version} is before 4.0; RBS signatures are only for 4.0+ databases")
+          end
+        rescue ArgumentError
+          error("#{path}: malformed version property: #{version.inspect}")
+        end
+        version
+      end
+
+      # --dry-run: 実 DB には書き込まず、複製に apply した統計だけを見せる
+      # (methodsince の apply_dry_run と同じ手口)
+      def apply_dry_run(importer, path)
+        Dir.mktmpdir do |tmp|
+          copy = File.join(tmp, 'db')
+          FileUtils.cp_r(path, copy)
+          importer.apply(MethodDatabase.new(copy))
+        end
+      end
+    end
+  end
+end

data/lib/bitclust/subcommands/setup_command.rb

@@ -20,7 +20,10 @@ module BitClust
         @prepare = nil
         @cleanup = nil
         @purge = nil
-        @versions = ["3.3.0", "3.4.0", "4.0.0"]
+        # teeny は付けない。#%if (version == "V") や #%version V の等値ゲートは
+        # 文字列一致なので、teeny 付きの版名で DB を作ると doctree CI・
+        # 生成済みドキュメントとゲートの判定がずれる
+        @versions = ["3.3", "3.4", "4.0"]
         @update = true
         @parser.banner = "Usage: #{File.basename($0, '.*')} setup [options]"
         @parser.on('--prepare', 'Prepare config file and checkout repository. Do not create database.') {

data/lib/bitclust/subcommands/statichtml_command.rb

@@ -13,6 +13,7 @@ require 'bitclust/subcommand'
 require 'bitclust/progress_bar'
 require 'bitclust/silent_progress_bar'
 require 'bitclust/search_index_generator'
+require 'bitclust/markdown_exporter'
 
 module BitClust
   module Subcommands
@@ -125,6 +126,7 @@ module BitClust
         @run_ruby_wasm = nil
         @sitemap_baseurl = nil
         @sitemap_paths = []
+        @markdown_output = false
         @parser.banner = "Usage: #{File.basename($0, '.*')} statichtml [options]"
         @parser.on('-o', '--outputdir=PATH', 'Output directory') do |path|
           begin
@@ -170,6 +172,9 @@ module BitClust
         @parser.on('--sitemap-baseurl=URL', 'Generate sitemap.xml under the output directory, with <loc> built from this base URL (e.g. https://docs.ruby-lang.org/ja/3.4/). Omit to skip sitemap.xml generation (default)') do |url|
           @sitemap_baseurl = url
         end
+        @parser.on('--markdown-output', 'Also write each page as Markdown (.md next to the .html), assembled from the preprocessed Markdown sources. Ignored for databases not created from a Markdown tree') do
+          @markdown_output = true
+        end
         @parser.on('--no-stop-on-syntax-error', 'Do not stop on syntax error') do |boolean|
           @stop_on_syntax_error = boolean
         end
@@ -185,8 +190,10 @@ module BitClust
         db = MethodDatabase.new(prefix.to_s)
         fdb = FunctionDatabase.new(prefix.to_s)
         manager = ScreenManager.new(@manager_config)
+        @markdown_exporter = MarkdownExporter.new(@urlmapper, @suffix) if @markdown_output
 
         db.transaction do
+          warn_markdown_output_skipped(db, "the method database")
           methods = {} #: Hash[String, Array[MethodEntry]]
           db.methods.each_with_index do |entry, i|
             next if entry.undefined?
@@ -203,6 +210,7 @@ module BitClust
         end
 
         fdb.transaction do
+          warn_markdown_output_skipped(fdb, "the function database")
           create_html_entries("capi", fdb.functions, manager, fdb)
         end
 
@@ -234,6 +242,7 @@ module BitClust
         FileUtils.cp(@manager_config[:themedir] + "script.js",
                      @outputdir.to_s, :verbose => @verbose, :preserve => true)
         copy_run_ruby_wasm_script if @run_ruby_wasm
+        copy_version_switcher_script
         FileUtils.cp(@manager_config[:themedir] + @manager_config[:favicon_url],
                      @outputdir.to_s, :verbose => @verbose, :preserve => true)
         Dir.mktmpdir do |tmpdir|
@@ -412,6 +421,19 @@ HERE
         end
       end
 
+      # Copy the version-switcher script. A themedir without it is
+      # tolerated: warn and skip instead of aborting the whole build.
+      def copy_version_switcher_script
+        src = @manager_config[:themedir] + "js" + "version_switcher.js"
+        unless src.file?
+          $stderr.puts "warning: #{src} not found; version switcher script not copied"
+          return
+        end
+        jsdir = @outputdir + "js"
+        FileUtils.mkdir_p(jsdir) unless jsdir.directory?
+        FileUtils.cp(src.to_s, jsdir.to_s, :verbose => @verbose, :preserve => true)
+      end
+
       def create_html_file(entry, manager, outputdir, db)
         e = entry.is_a?(Array) ? entry.sort.first : entry
         case e.type_id
@@ -419,6 +441,7 @@ HERE
           @urlmapper.bitclust_html_base = '..'
           path = outputdir + e.type_id.to_s + html_filename(encodename_package(e.name), @suffix)
           create_html_file_p(entry, manager, path, db)
+          create_markdown_file_p(e, path, db)
         when :function
           create_html_function_file(entry, manager, outputdir, db)
         else
@@ -435,6 +458,11 @@ HERE
         path = outputdir + e.type_id.to_s + encodename_package(e.klass.name) +
           e.typechar + html_filename(encodename_package(name), @suffix)
         create_html_file_p(entries, manager, path, db)
+        if markdown_export?(db)
+          create_file(markdown_path(path),
+                      @markdown_exporter.method_page(method_name, entries.sort),
+                      :verbose => @verbose)
+        end
       end
 
       def create_html_function_file(entry, manager, outputdir, db)
@@ -442,6 +470,7 @@ HERE
         @urlmapper.bitclust_html_base = '..'
         path = outputdir + entry.type_id.to_s + html_filename(entry.name, @suffix)
         create_html_file_p(entry, manager, path, db)
+        create_markdown_file_p(entry, path, db)
       end
 
       def create_html_file_p(entry, manager, path, db)
@@ -453,6 +482,36 @@ HERE
         record_sitemap_path(path)
       end
 
+      # --markdown-output は Markdown ツリー由来の DB でのみ有効。
+      # ソースが md でない(凍結版 RD など)DB では何も出力しない
+      def markdown_export?(db)
+        @markdown_output && db.properties['source_format'] == 'markdown'
+      end
+
+      def warn_markdown_output_skipped(db, label)
+        return if !@markdown_output || db.properties['source_format'] == 'markdown'
+        $stderr.puts "warning: --markdown-output is ignored for #{label}: it was not created from a Markdown tree"
+      end
+
+      def create_markdown_file_p(entry, html_path, db)
+        return unless markdown_export?(db)
+        content =
+          case entry.type_id
+          when :library then @markdown_exporter.library_page(_ = entry)
+          when :class then @markdown_exporter.class_page(_ = entry)
+          when :doc then @markdown_exporter.doc_page(_ = entry)
+          when :function then @markdown_exporter.function_page(_ = entry)
+          else return
+          end
+        create_file(markdown_path(html_path), content, :verbose => @verbose)
+      end
+
+      def markdown_path(html_path)
+        s = html_path.to_s
+        s = s.end_with?(@suffix) ? s[0, s.length - @suffix.length].to_s : s
+        Pathname.new("#{s}.md")
+      end
+
       def create_file(path, str, options = {})
         verbose = options[:verbose]
         $stderr.print("creating #{path} ...") if verbose

data/lib/bitclust/version.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 module BitClust
-  VERSION = "1.6.0"
+  VERSION = "1.7.0"
 end

data/lib/bitclust-irb.rb

@@ -0,0 +1,2 @@
+# frozen_string_literal: true
+require 'bitclust/irb'

data/test/test_irb_plugin.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+require 'test/unit'
+require 'tmpdir'
+require 'fileutils'
+require 'stringio'
+require 'bitclust'
+require 'bitclust/methoddatabase'
+require 'bitclust/searcher'
+
+# bitclust-irb gem の irb コマンド(refe)。
+#
+# テストリスト:
+# [x] TerminalView が io: に出力する(既定は従来どおり $stdout)
+# [x] Irb.lookup がメソッドを検索して整形結果を io へ書く
+# [x] Irb.lookup がクラスも引ける
+# [x] 空のパターンは使い方を表示して例外にしない
+# [x] 見つからないパターンはメッセージを io へ書いて例外にしない
+# [x] require で IRB::Command::Base のサブクラスとして登録される
+class TestBitClustIrbPlugin < Test::Unit::TestCase
+  FOO_MD = <<~'MD'
+    ---
+    library: foo
+    ---
+    # class Foo < Object
+
+    クラスの説明。
+
+    ## Instance Methods
+
+    ### def bar -> nil
+
+    bar の説明。
+  MD
+
+  def build_markdown_db(dir)
+    api = File.join(dir, 'manual', 'api')
+    FileUtils.mkdir_p(File.join(api, 'foo'))
+    File.write(File.join(api, 'foo.md'), "---\ntype: library\n---\nfoo ライブラリ。\n")
+    File.write(File.join(api, 'foo', 'Foo.md'), FOO_MD)
+    prefix = File.join(dir, 'db')
+    db = BitClust::MethodDatabase.new(prefix)
+    db.init
+    db.transaction do
+      db.propset('version', '3.4')
+      db.propset('encoding', 'utf-8')
+    end
+    db.transaction do
+      db.update_by_markdowntree(api)
+    end
+    BitClust::MethodDatabase.new(prefix)
+  end
+
+  def with_db(&block)
+    Dir.mktmpdir do |dir|
+      yield build_markdown_db(dir)
+    end
+  end
+
+  def test_terminal_view_writes_to_given_io
+    out = StringIO.new
+    view = BitClust::TerminalView.new(BitClust::Plain.new, {}, io: out)
+    view.send(:puts, 'hello')
+    assert_equal("hello\n", out.string)
+  end
+
+  def test_lookup_method
+    require 'bitclust/irb'
+    with_db do |db|
+      out = StringIO.new
+      BitClust::Irb.lookup('Foo#bar', db: db, io: out)
+      assert_match(/Foo#bar/, out.string)
+      assert_match(/bar の説明。/, out.string)
+    end
+  end
+
+  def test_lookup_class
+    require 'bitclust/irb'
+    with_db do |db|
+      out = StringIO.new
+      BitClust::Irb.lookup('Foo', db: db, io: out)
+      assert_match(/class Foo < Object/, out.string)
+      assert_match(/クラスの説明。/, out.string)
+    end
+  end
+
+  def test_lookup_empty_pattern_shows_usage
+    require 'bitclust/irb'
+    with_db do |db|
+      out = StringIO.new
+      assert_nothing_raised do
+        BitClust::Irb.lookup('', db: db, io: out)
+      end
+      assert_match(/refe/, out.string)
+    end
+  end
+
+  def test_lookup_not_found_reports_instead_of_raising
+    require 'bitclust/irb'
+    with_db do |db|
+      out = StringIO.new
+      assert_nothing_raised do
+        BitClust::Irb.lookup('NoSuchClass#no_such_method', db: db, io: out)
+      end
+      assert_match(/no such method/, out.string)
+    end
+  end
+
+  def test_command_is_registered_for_irb
+    begin
+      require 'irb/command'
+    rescue LoadError
+      omit 'irb >= 1.13 is not available'
+    end
+    require 'bitclust/irb'
+    assert(BitClust::Irb::RefeCommand < ::IRB::Command::Base)
+    assert_match(/るりま|リファレンス/, BitClust::Irb::RefeCommand.description)
+  end
+end

data/test/test_link_checker.rb

@@ -38,7 +38,7 @@ class TestLinkChecker < Test::Unit::TestCase
 
     ## Class Methods
 
-    ### def baz -> nil
+    ### def Foo.baz -> nil
 
     baz です。