bitclust-core 1.3.0 → 1.6.0

data/lib/bitclust/mdparser.rb

@@ -0,0 +1,347 @@
+# frozen_string_literal: true
+#
+# bitclust/mdparser.rb
+#
+# Markdown ソースを直接パースして DB エントリを作るパーサ（フェーズ3 M3）。
+#
+# RRDParser のサブクラスとして、行レベルのディスパッチだけを Markdown 記法
+# （MARKUP_SPEC）に差し替える。構造の組み立て（Context・Signature・Chunk）は
+# すべて RRDParser から継承する。エントリの source には md 断片がそのまま入る。
+#
+# - `= class X < Y` → `# class X < Y`
+# - `== Class Methods` 等 → `## Class Methods`（名称は同一）
+# - `--- sig` → `### def sig` / `### module_function def` / `### const` / `### gvar`
+# - category/require/sublibrary・include/extend/alias → front matter
+# - `#@since` 等の指令は md でも同一記法のため Preprocessor は無変更で使う
+#   （front matter 内の `#@` 行も先に版解決される）
+
+require 'bitclust/rrdparser'
+require 'bitclust/functionreferenceparser'
+require 'bitclust/methodsignature'
+
+module BitClust
+
+  # C API リファレンス（manual/capi）の md を直接パースする。
+  # capi の md は本文見出しを持たず、### 全行がシグネチャ
+  # （--- <C sig> 相当、キーワード無し）。source は本文の md がそのまま入る
+  class MDFunctionParser < FunctionReferenceParser
+    private
+
+    def file_entries(f)
+      f.skip_blank_lines
+      f.while_match(/\A### /) do |header|
+        entry header.sub(/\A###/, '').strip, f.break(/\A### /)
+        f.skip_blank_lines
+      end
+    end
+  end
+
+  class MDParser < RRDParser
+
+    # doc ページの md からタイトル（# 見出し、アンカー付き含む）と本文を分ける
+    # （RRDParser.split_doc の md 版）
+    def MDParser.split_doc(source)
+      if m = /^#( +(.*?))(?: \{#[^}]+\})?\r?\n/.match(source)
+        return ($2 || raise), m.post_match
+      end
+      return ["", source]
+    end
+
+    # メソッド系シグネチャ（キーワード付き h3）
+    SIG_RE = /\A### (?:module_function def |def |const |gvar )/
+    # H1（エンティティ見出し）。エスケープされた行頭リテラル \# は除外
+    H1_RE = /\A#[^#]/
+    # H2（レベル2セクション見出し）
+    H2_RE = /\A##[^#]/
+    # klass.source / library.source の終端（H1・H2・シグネチャ）
+    BREAK_RE = /\A##?[^#]|\A### (?:module_function def |def |const |gvar )/
+
+    def parse(f, libname, params = {})
+      @context = Context.new(@db, libname)
+      f = LineInput.new(Preprocessor.wrap(f, params))
+      @front_matter = read_front_matter(f)
+      do_parse f
+      @context.library
+    end
+
+    private
+
+    # BREAK_RE まで行を収集する（f.break のフェンス対応版）。
+    # コードフェンス内の行頭 `# コメント` 等が H1/H2 と衝突しないよう、
+    # フェンス内は無条件に本文として消費する
+    def md_break(f)
+      lines = [] #: Array[String?]
+      fence_len = nil
+      while (line = f.peek)
+        if fence_len
+          lines.push(f.gets)
+          fence_len = nil if line =~ /\A`{#{fence_len}}\s*$/
+        elsif line =~ /\A(`{3,})/
+          fence_len = ($1 || raise).length
+          lines.push(f.gets)
+        elsif line =~ BREAK_RE
+          break
+        else
+          lines.push(f.gets)
+        end
+      end
+      lines
+    end
+
+    # 断片の front matter を @front_matter へマージ（リストは連結、
+    # スカラーは後勝ち）
+    def merge_front_matter(fm)
+      fm.each do |k, v|
+        if v.is_a?(Array) && @front_matter[k].is_a?(Array)
+          @front_matter[k] |= v
+        else
+          @front_matter[k] = v
+        end
+      end
+    end
+
+    # front matter（--- ... ---）を読む。YAML のサブセット:
+    # スカラー（type/library/category/since/until）とリスト
+    # （include/extend/alias/require/sublibrary）のみ。#@/#% 行は
+    # Preprocessor で版解決済みの残り（#@#/#%# コメント等）なので読み飛ばす
+    def read_front_matter(f)
+      fm = {} #: front_matter
+      return fm unless f.peek && f.peek =~ /\A---\s*$/
+      f.gets
+      key = nil
+      while (line = f.gets)
+        break if line =~ /\A---\s*$/
+        case line
+        when /\A\#[@%]/
+          next
+        when /\A(\w+):\s*$/
+          key = $1
+          fm[key] = []
+        when /\A(\w+):\s*(.+?)\s*$/
+          fm[$1] = ($2 || raise).sub(/\A"(.*)"\z/, '\1')
+          key = nil
+        when /\A\s+-\s+(\S.*?)\s*$/
+          list = fm[key]
+          list << $1 if key && list.is_a?(Array)
+        end
+      end
+      fm
+    end
+
+    def do_parse(f)
+      f.skip_blank_lines
+      # #@include 展開で断片の front matter がストリーム先頭に現れる
+      # （rdoc/parser/simple → parsers/parse_simple の require リスト等）。
+      # 連続するブロックを読んでメタデータをマージする
+      while f.peek && f.peek =~ /\A---\s*$/
+        merge_front_matter read_front_matter(f)
+        f.skip_blank_lines
+      end
+      # RRDParser と同じく未指定でも呼ぶ（category=nil を明示的に設定）
+      @context.categorize @front_matter['category'] if @front_matter['type'] == 'library'
+      Array(@front_matter['require']).each { |r| @context.require r }
+      Array(@front_matter['sublibrary']).each { |s| @context.sublibrary s }
+      prose = md_break(f).join('').rstrip
+      # メンバーファイル（library: 参照のみ）のパースで lib 本文を
+      # 上書きしないよう、lib ファイル（type: library）のときだけ設定する
+      @context.library.source = prose if @front_matter['type'] == 'library'
+      read_classes f
+      if line = f.gets   # error
+        case line
+        when H2_RE
+          parse_error "met level-2 header in library document; maybe you forgot level-1 header", line
+        when SIG_RE
+          parse_error "met bare method entry in library document; maybe you forgot reopen/redefine level-1 header", line
+        else
+          parse_error "unexpected line in library document", line
+        end
+      end
+    end
+
+    RELATION_KEYS = %w[include extend alias].freeze
+
+    def read_classes(f)
+      entity_count = 0
+      f.while_match(H1_RE) do |line|
+        entity_count += 1
+        if entity_count > 1 && RELATION_KEYS.any? { |k| @front_matter.key?(k) }
+          # 案B: 関係を持つファイルは単一エンティティ（front matter の
+          # include/extend/alias の帰属が曖昧になるため）
+          parse_error "multiple entities in a file with front matter relations", line
+        end
+        type, name, superclass = *parse_level1_header(line)
+        case type
+        when 'class'
+          @context.define_class name, (superclass || 'Object'), location: line.location
+          read_class_body f
+        when 'module'
+          parse_error "superclass given for module", line  if superclass
+          @context.define_module name, location: line.location
+          read_class_body f
+        when 'object'
+          @context.define_object name, superclass, location: line.location
+          read_object_body f
+        when 'reopen'
+          @context.reopen_class name
+          read_reopen_body f
+        when 'redefine'
+          @context.redefine_class name
+          read_reopen_body f
+        else
+          parse_error "wrong level-1 header", line
+        end
+      end
+    end
+
+    def parse_level1_header(line)
+      m = /\A(\S+)\s*([^\s<]+)(?:\s*<\s*(\S+))?\z/.match(line.sub(/\A#/, '').strip)
+      unless m
+        parse_error "level-1 header syntax error", line
+      end
+      return m[1], m[2], m[3]
+    end
+
+    # 関係（include/extend/alias）は front matter が置き場（案B）。
+    # ただし #@include 断片（rdoc/parsers/parse_rb 等）は rd 形式の
+    # 関係行を本文に保持しているため、RRDParser 同様ストリームからも読む
+    def read_aliases(f)
+      Array(@front_matter['alias']).each { |name| @context.alias name }
+      f.while_match(/\Aalias\s/) do |line|
+        @context.alias line.split[1]
+      end
+    end
+
+    def read_includes(f, reopen = false)
+      Array(@front_matter['include']).each do |name|
+        reopen ? @context.dynamic_include(name) : @context.include(name)
+      end
+      f.while_match(/\Ainclude\s/) do |line|
+        name = line.split[1]
+        reopen ? @context.dynamic_include(name) : @context.include(name)
+      end
+    end
+
+    def read_extends(f, reopen = false)
+      Array(@front_matter['extend']).each do |name|
+        reopen ? @context.dynamic_extend(name) : @context.extend(name)
+      end
+      f.while_match(/\Aextend\s/) do |line|
+        name = line.split[1]
+        reopen ? @context.dynamic_extend(name) : @context.extend(name)
+      end
+    end
+
+    def read_class_body(f)
+      f.skip_blank_lines
+      read_aliases f
+      read_extends f
+      read_includes f
+      f.skip_blank_lines
+      @context.klass&.source = md_break(f).join('').rstrip
+      read_level2_blocks f
+    end
+
+    def read_reopen_body(f)
+      f.skip_blank_lines
+      read_extends f, true
+      read_includes f, true
+      f.skip_blank_lines
+      read_level2_blocks f
+    end
+
+    def read_object_body(f)
+      f.skip_blank_lines
+      read_aliases f
+      read_extends f
+      f.skip_blank_lines
+      @context.klass&.source = md_break(f).join('').rstrip
+      @context.visibility = :public
+      @context.type = :singleton_method
+      read_level2_blocks f
+    end
+
+    def read_level2_blocks(f)
+      read_entries f
+      f.skip_blank_lines
+      f.while_match(H2_RE) do |line|
+        case line.sub(/\A##/, '').strip
+        when /\A((?:public|private|protected)\s+)?(?:(class|singleton|instance)\s+)?methods?\z/i
+          # @type var visibility: :public | :private | :protected
+          visibility = ($1 || 'public').downcase.strip.intern
+          @context.visibility = visibility
+          t = ($2 || 'instance').downcase.sub(/class/, 'singleton')
+          @context.type = _ = "#{t}_method".intern
+        when /\AModule\s+Functions?\z/i
+          @context.module_function
+        when /\AConstants?\z/i
+          @context.constant
+        when /\ASpecial\s+Variables?\z/i
+          @context.special_variable
+        else
+          parse_error "unknown level-2 header", line
+        end
+        read_entries f
+      end
+    end
+
+    def read_chunks(f)
+      f.skip_blank_lines
+      result = [] #: Array[Chunk]
+      f.while_match(SIG_RE) do |line|
+        f.ungets line
+        result.push read_chunk(f)
+      end
+      result
+    end
+
+    def read_chunk(f)
+      # シグネチャ行の直後には {: ...} 属性行を置ける(rd 側と同じ)。
+      # 属性行を挟んでもひとつのチャンク(別名グループ)として読む
+      header = [] #: Array[String]
+      sig_lines = [] #: Array[String]
+      while f.next?
+        if SIG_RE =~ f.peek
+          line = f.gets or raise
+          header.push line
+          sig_lines.push line
+        elsif !sig_lines.empty? && METHOD_ATTRIBUTE_LINE_RE =~ f.peek
+          header.push(f.gets || raise)
+        else
+          break
+        end
+      end
+      body = md_break(f)
+      src = (header + body).join('')
+      src.location = sig_lines[0].location
+      sigs = sig_lines.map {|line| method_signature(line) }
+      mainsig = check_chunk_signatures(sigs, sig_lines[0])
+      names = sigs.map {|s| s.name }.compact.uniq.sort
+      Chunk.new(mainsig, names, src)
+    end
+
+    # md シグネチャ行を rd 形式（--- ...）へ落とし、既存の
+    # Signature パースを継承する。エラー時は元の行を報告する
+    def method_signature(line)
+      rd_line = line.sub(SIG_RE, '--- ')
+      begin
+        # 描画（MethodSignature.parse）が受理できないシグネチャは
+        # statichtml まで進んでから落ちる（か、誤った名前で DB に入る）ので
+        # パース時に拒否する。RBS 形式（def name:）や self. プレフィクスが該当
+        MethodSignature.parse(rd_line)
+      rescue ParseError
+        parse_error "unsupported method signature", line
+      end
+      case
+      when m = SIGNATURE.match(rd_line)
+        klass, typemark_, name = m.captures
+        typemark = _ = typemark_
+        Signature.new(klass, typemark, name)
+      when m = GVAR.match(rd_line)
+        Signature.new(nil, '$', (m[1] || raise)[1..-1])
+      else
+        parse_error "wrong method signature", line
+      end
+    end
+  end
+
+end

data/lib/bitclust/messagecatalog.rb

@@ -53,7 +53,7 @@ module BitClust
 
     def MessageCatalog.load_with_locales(prefix, locales)
       path, loc = find_catalog(prefix, locales)
-      path ? load_file(path, loc) : new({}, 'C')
+      path ? load_file(path, loc || raise) : new({}, 'C')
     end
 
     def MessageCatalog.env_locales
@@ -72,10 +72,10 @@ module BitClust
     private_class_method :find_catalog
 
     def MessageCatalog.load_file(path, locale)
-      h = {}
+      h = {} #: Hash[String, String]
       fopen(path, 'r:UTF-8') {|f|
         f.each do |key|
-          h[key.chomp] = f.gets.chomp
+          h[key.chomp] = (f.gets || raise).chomp
         end
       }
       new(h, locale)

data/lib/bitclust/method_since_calculator.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+#
+# bitclust/method_since_calculator.rb
+#
+
+require 'bitclust/exception'
+
+module BitClust
+
+  # 複数バージョンの DB(バージョンラダー)からメソッド名別の初出/削除
+  # バージョンを算出し、対象 DB のメソッドエントリへ書き込む(bitclust#132 P2)。
+  #
+  # ライブラリは意図的に無視する: 同じメソッドが版によって別ライブラリの
+  # 下でドキュメント化されていても、同一メソッドとして union で扱う。
+  #
+  # 算出値は「著者が明示した値(将来 P4 で {: since ...} 等から記録される
+  # 想定)」より優先度が低い。#apply は MethodEntry#fill_since/fill_until を
+  # 使うため、既に値がある名前は上書きしない。
+  class MethodSinceCalculator
+
+    def initialize(dbs)
+      versions = dbs.map {|db| db.propget('version') }
+      versions.each do |v|
+        if v.nil? || v.empty?
+          raise UserError, "database has no version property"
+        end
+      end
+      dup = versions.tally.select {|_, n| n > 1 }.keys
+      unless dup.empty?
+        raise UserError, "duplicate version(s) in ladder: #{dup.join(', ')}"
+      end
+      sorted = dbs.sort_by {|db| Gem::Version.new(db.propget('version') || raise) }
+      @versions = sorted.map {|db| db.propget('version') || raise }
+      @ladder = sorted
+      @first = {} #: Hash[key, String]
+      @last  = {} #: Hash[key, String]
+    end
+
+    # ラダーの各 DB を1つずつ走査して [クラス名, typechar, 生名] ごとの
+    # 初出/最終出現バージョンを記録する。走査済みの DB への参照は
+    # メモリを膨らませないようその場で捨てる
+    def scan
+      ladder = @ladder or raise "scan was already called"
+      @ladder = nil
+      until ladder.empty?
+        db = ladder.shift
+        version = db.propget('version') || raise
+        db.classes.each do |c|
+          c.entries.each do |m|
+            next if m.kind == :undefined
+            m.names.each do |name|
+              key = [c.name, m.typechar, name] #: key
+              @first[key] ||= version
+              @last[key] = version
+            end
+          end
+        end
+      end
+      self
+    end
+
+    # key = [クラス名, typechar, 生名]。ラダー最古版から存在する(フロア)
+    # 場合は「不明」を意味するので nil を返す
+    def since_for(key)
+      first = @first[key] or return nil
+      first == (@versions.first || raise) ? nil : first
+    end
+
+    # ラダー最新版でも存在する場合は「まだ削除されていない」ので nil。
+    # そうでなければ最終出現バージョンの次のラダーバージョン(削除された版)
+    def until_for(key)
+      last = @last[key] or return nil
+      return nil if last == (@versions.last || raise)
+      idx = @versions.index(last) or raise "must not happen: #{last.inspect}"
+      @versions[idx + 1] || raise
+    end
+
+    # 対象 DB の各メソッドエントリへ算出済みの since/until を書き込む。
+    # target_db のバージョンはラダーに含まれていなければならない。
+    # 既に値がある名前は fill_since/fill_until の仕様により上書きされない
+    # (著者による明示値が算出値より優先される)。冪等: 2回目の apply は
+    # 何も変更しない(floor_skipped を除く)
+    def apply(target_db)
+      version = target_db.propget('version')
+      unless @versions.include?(version)
+        raise UserError, "#{version.inspect} is not one of the ladder versions: #{@versions.join(', ')}"
+      end
+      stats = {entries_updated: 0, since_filled: 0, until_filled: 0, floor_skipped: 0} #: stats
+      target_db.classes.each do |c|
+        c.entries.each do |m|
+          next if m.kind == :undefined
+          changed = false
+          m.names.each do |name|
+            key = [c.name, m.typechar, name] #: key
+            if since_v = since_for(key)
+              if m.fill_since(name, since_v)
+                stats[:since_filled] += 1
+                changed = true
+              end
+            else
+              stats[:floor_skipped] += 1
+            end
+            if (until_v = until_for(key)) && m.fill_until(name, until_v)
+              stats[:until_filled] += 1
+              changed = true
+            end
+          end
+          if changed
+            m.save
+            stats[:entries_updated] += 1
+          end
+        end
+      end
+      stats
+    end
+  end
+end

data/lib/bitclust/methoddatabase.rb

@@ -18,6 +18,7 @@ require 'bitclust/refsdatabase'
 require 'bitclust/rrdparser'
 require 'bitclust/exception'
 require 'fileutils'
+require 'pathname'
 
 module BitClust
 
@@ -47,14 +48,15 @@ module BitClust
     attr_writer :refs
 
     def init
-      FileUtils.rm_rf @prefix
-      FileUtils.mkdir_p @prefix
-      Dir.mkdir "#{@prefix}/library"
-      Dir.mkdir "#{@prefix}/class"
-      Dir.mkdir "#{@prefix}/method"
-      Dir.mkdir "#{@prefix}/doc"
-      FileUtils.touch "#{@prefix}/properties"
-      FileUtils.touch "#{@prefix}/refs"
+      prefix = @prefix || raise
+      FileUtils.rm_rf prefix
+      FileUtils.mkdir_p prefix
+      Dir.mkdir "#{prefix}/library"
+      Dir.mkdir "#{prefix}/class"
+      Dir.mkdir "#{prefix}/method"
+      Dir.mkdir "#{prefix}/doc"
+      FileUtils.touch "#{prefix}/properties"
+      FileUtils.touch "#{prefix}/refs"
     end
 
     #
@@ -162,6 +164,56 @@ module BitClust
       RRDParser.new(self).parse_file(path, libname, properties())
     end
 
+    # Markdown ツリー（manual/api）を直接パースして DB を更新する（M3）。
+    # front matter の library: が所属を表すため、ライブラリごとに
+    # lib ファイル → メンバーファイル（reopen/redefine のみのファイルは後置。
+    # dynamic include の対象 module が先に定義されている必要があるため）の
+    # 順でパースする。版ゲート（since/until）外のライブラリ/メンバーはスキップ。
+    # エントリの source には md 断片が入り、source_location は md の実パスを指す
+    def update_by_markdowntree(md_root)
+      require 'bitclust/markdown_tree'
+      require 'bitclust/mdparser'
+      @md_root = md_root
+      # 描画層（screen.rb）が MDCompiler を選択するためのマーカー
+      propset 'source_format', 'markdown'
+      tree = MarkdownTree.scan(md_root)
+      version = properties()["version"]
+      tree.libraries.sort.each do |libname, lib|
+        next unless md_version_covers?(version, lib[:since], lib[:until])
+        lib_entry = MDParser.new(self).parse_file(File.join(md_root, lib[:path]), libname, properties())
+        lib_location = lib_entry.source_location
+        # 多重所属（ゲート付き library リスト）は、この版でゲートが生きている
+        # membership を持つライブラリだけがメンバーとして取り込む
+        members = tree.entities.select { |_, e|
+          e[:memberships].any? { |m|
+            m[:library] == libname && md_version_covers?(version, m[:since], m[:until])
+          }
+        }
+        sorted = members.keys.sort_by { |path|
+          reopen_only = members[path][:kinds].all? { |kind, _| %w[reopen redefine].include?(kind) }
+          [reopen_only ? 1 : 0, path]
+        }
+        sorted.each do |path|
+          entity = members[path]
+          next unless md_version_covers?(version, entity[:since], entity[:until])
+          MDParser.new(self).parse_file(File.join(md_root, path), libname, properties())
+        end
+        # parse_file は毎回 library の source_location を上書きするため
+        # lib ファイルの値へ戻す
+        lib_entry.source_location = lib_location
+      end
+    end
+
+    # since は「その版以降」、until は「その版未満」（ブリッジの
+    # #@since/#@until ラッパーと同じ意味論）
+    def md_version_covers?(version, since_version, until_version)
+      v = Gem::Version.new(version)
+      return false if since_version && v < Gem::Version.new(since_version)
+      return false if until_version && v >= Gem::Version.new(until_version)
+      true
+    end
+    private :md_version_covers?
+
     def refs
       @refs ||= RefsDatabase.load(realpath('refs'))
     end
@@ -176,10 +228,12 @@ module BitClust
     end
 
     def copy_doc
+      return copy_doc_md if @md_root
+      return unless @root
       root_path = Pathname.new(@root).expand_path
       Dir.glob("#{@root}/../../doc/**/*.rd").each do |f|
         if %r!\A#{Regexp.escape(@root)}/\.\./\.\./doc/([-\./\w]+)\.rd\z! =~ f
-          id = libname2id($1)
+          id = libname2id($1 || raise)
           se = DocEntry.new(self, id)
           s = Preprocessor.read(f, properties)
           title, source = RRDParser.split_doc(s)
@@ -192,6 +246,65 @@ module BitClust
       end
     end
 
+    # ネイティブ md ツリーの doc ページ登録（manual/api の隣の manual/doc）。
+    # ページ = 他の doc ファイルから #@include 参照されていない .md。
+    # source には md がそのまま入り、source_location は md の実パスを指す
+    def copy_doc_md
+      require 'bitclust/mdparser'
+      # source_location は md_root と同じ形で格納する（api 側と同じ慣例。
+      # Rakefile の相対 manual/api なら manual/doc/... になる）。絶対化すると
+      # Windows のドライブレターのコロンで file:line 分割が壊れ、
+      # 編集リンクも実行環境のパス依存になる
+      doc_root = Pathname.new(File.join(@md_root, '..', 'doc')).cleanpath.to_s
+      return unless File.directory?(doc_root)
+      files = Dir.glob("#{doc_root}/**/*.md").sort
+      referenced = files.flat_map { |f|
+        base = File.dirname(f)
+        File.read(f).scan(/^\#[@%]include\((.*?)\)/).map { |t|
+          p = File.expand_path(t[0] || raise, base)
+          [p, "#{p}.md", p.sub(/\.rd\z/, '.md')]
+        }.flatten
+      }.to_set
+      version = properties()["version"]
+      files.each do |f|
+        next if referenced.include?(File.expand_path(f))
+        # front matter の since/until でページ自体をバージョンで出し分ける
+        # （ライブラリ側 update_by_markdowntree と同じ意味論）。範囲外の版では
+        # ページを登録しない（例: doc/spec/safelevel は until: "3.2" で 3.2 以降
+        # 非生成）
+        since_version, until_version = doc_md_version_range(f)
+        next unless md_version_covers?(version, since_version, until_version)
+        id = libname2id(f.delete_prefix("#{doc_root}/").sub(/\.md\z/, ''))
+        se = DocEntry.new(self, id)
+        s = Preprocessor.read(f, properties)
+        title, source = MDParser.split_doc(s)
+        se.title = title
+        se.source = source
+        se.source_location = Location.new(f, 1)
+        se.save
+      end
+    end
+    private :copy_doc_md
+
+    # doc ページの先頭 front matter から since/until を読む
+    # （MarkdownTree.scan がライブラリ/エンティティで読むのと同じ書式）。
+    # front matter が無い、または since/until を持たなければ [nil, nil]。
+    def doc_md_version_range(path)
+      since_version = nil
+      until_version = nil
+      File.open(path, 'r:UTF-8') do |io|
+        first = io.gets
+        return [nil, nil] unless first && first =~ /\A---\s*$/
+        while (line = io.gets)
+          break if line =~ /\A---\s*$/
+          since_version = $1 if line =~ /\Asince:\s*"?([^"\s]+)"?/
+          until_version = $1 if line =~ /\Auntil:\s*"?([^"\s]+)"?/
+        end
+      end
+      [since_version, until_version]
+    end
+    private :doc_md_version_range
+
     #
     # Doc Entry
     #
@@ -311,7 +424,7 @@ module BitClust
       check_transaction
       id = classname2id(name)
       if exist?("class/#{id}")
-        c = load_class(id)
+        c = load_class(id) || raise
         c.clear
       else
         c = (@classmap[id] ||= ClassEntry.new(self, id))
@@ -331,6 +444,7 @@ module BitClust
     private :load_class
 
     def load_extent(entry_class)
+      # @type var h: Hash[String, untyped]
       h = {}
       id_extent(entry_class).each do |id|
         h[id] = entry_class.new(self, id)
@@ -382,10 +496,6 @@ module BitClust
       fetch_class(spec.klass).fetch_method(spec)
     end
 
-    def search_method(pattern)
-      search_methods(pattern).first
-    end
-
     def search_methods(pattern)
       result = _search_methods(pattern)
       if result.fail?