Markdown 対応で追加されたコードに RBS 型定義を付ける

rake sig（rbs subtract）が検出する型定義の不足を解消する:

- Markdown 対応で追加された 13 ファイル分の sig を新規作成
  （mdparser, mdcompiler, markdown_to_rrd, rrd_to_markdown,
    markdown_tree, markdown_bridge, markdown_orchestrator,
    include_graph, include_pruner, entity_splitter, whole_file_gate,
    capi_converter, doc_converter）
- 既存クラスに追加された markdown 系メンバーを既存 sig へ追記
  （MethodDatabase#update_by_markdowntree・copy_doc_md、
    TemplateScreen#markdown_source?・html_base、
    UpdateCommand#prepare_markdowntree ほか、
    StatichtmlCommand#create_search_index・SEARCH_JS_FILES）
- database_propkey へ 'source_format' を追加、Rouge の最小スタブを追加、
  RDCompiler::option の :catalog を実装に合わせて省略可へ、
  Location の line を Integer? へ（line 不明の Location があるため）

steep check をエラー 0・警告 0 にする（従来はエラー 471・警告 317）:

- マッチ直後で非 nil が保証される $1 等の参照は
  既存慣行の ($1 || raise) 形に揃える
- steep が推論できない空リテラルやブロック越し代入には
  インライン型注釈（#: / @type var）を付ける
- File.write(Pathname, ...) → Pathname#write 等、
  rbs core の型が受けない等価な呼び出しを書き換える

挙動の変更はない（テスト 17589 件 green・rbs validate / rake sig 通過）。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: znz

lib/bitclust/doc_converter.rb

@@ -27,7 +27,7 @@ def reduce(rrd)
         when /\A(={1,4}\[a:[^\]]+\])\s{2,}(.*)/m
           "#{$1} #{$2}"                          # アンカー見出しの余分なスペース
         when /\A\t+/
-          line.sub(/\A\t+/) { ' ' * $&.length }  # 行頭タブ（doc の散文1行のみ）
+          line.sub(/\A\t+/) { ' ' * ($& || raise).length }  # 行頭タブ（doc の散文1行のみ）
         when /\A\#@include\((?:\.\.\/)+api\/src\//
           # 旧レイアウト ../api/src/X → 新レイアウト ../api/X
           # （manual/ 配下では src 階層が無い。ブリッジが逆変換する）
@@ -54,7 +54,7 @@ def files(doc_root)
         base = File.dirname(f)
         File.read(File.join(doc_root, f))
             .scan(/^\#@include\((?!(?:\.\.\/)+api\/)(.*?)\)/)
-            .map { |t| File.expand_path(base == '.' ? t[0] : File.join(base, t[0]), '/')
+            .map { |t| File.expand_path(base == '.' ? (t[0] || raise) : File.join(base, t[0] || raise), '/')
                            .delete_prefix('/') }
       }
       (pages + (all & referenced)).sort

lib/bitclust/entity_splitter.rb

@@ -29,7 +29,7 @@ module EntitySplitter
     # H1 を含まないゲート（散文の版分岐・gated relations）は触らない。
     def resolve_header_gates(src, scope)
       lines = src.lines
-      out = []
+      out = [] #: Array[String]
       i = 0
       while i < lines.length
         line = lines[i]
@@ -87,7 +87,8 @@ def contains_entity_h1?(lines)
     # ベースセグメントとして返す。連結すると入力に一致する。
     def segments(src)
       lines = src.lines
-      boundaries = []   # [行index, エンティティ名, ゲート付きか]
+      # [行index, エンティティ名, ゲート付きか]
+      boundaries = [] #: Array[[Integer, String?, bool]]
       depth = 0
       lines.each_with_index do |line, i|
         case line
@@ -111,25 +112,25 @@ def segments(src)
         next true unless gated
         stop = idx + 1 < boundaries.length ? boundaries[idx + 1][0] : lines.length
         gate_wraps_segment?(lines, start, stop)
-      }.map { |(start, name, _), _| [start, name] }
+      }.map { |(start, name, _), _| [start, name] } #: Array[[Integer, String?]]
       return nil if boundaries.empty?
-      if lines[0...boundaries.first[0]].all? { |l| l =~ BLANK_RE }
+      if (lines[0...(boundaries.first || raise)[0]] || raise).all? { |l| l =~ BLANK_RE }
         boundaries[0] = [0, boundaries[0][1]]   # 先頭の空行は最初のセグメントへ
       else
         boundaries.unshift([0, nil])            # ライブラリ概要部（ベースセグメント）
       end
 
       boundaries.each_with_index.map do |(start, name), idx|
         stop = idx + 1 < boundaries.length ? boundaries[idx + 1][0] : lines.length
-        [name, lines[start...stop].join]
+        [name, (lines[start...stop] || raise).join]
       end
     end
 
     # start のゲート開き行に対応する #@end がセグメント終端（末尾の空行は許容）に
     # あるか。ゲートがセグメント全体を包むときのみ真
     def gate_wraps_segment?(lines, start, stop)
       depth = 0
-      close = nil
+      close = nil #: Integer?
       (start...stop).each do |i|
         case lines[i]
         when BLOCK_OPEN_RE then depth += 1
@@ -142,7 +143,7 @@ def gate_wraps_segment?(lines, start, stop)
         end
       end
       return false unless close
-      lines[(close + 1)...stop].all? { |l| l =~ BLANK_RE }
+      (lines[(close + 1)...stop] || raise).all? { |l| l =~ BLANK_RE }
     end
 
     # エンティティ名 → 出力ファイル名（拡張子なし）。既存の命名規約に合わせ :: → __
@@ -171,15 +172,15 @@ def header_relations?(src)
     def gate_condition(line)
       return nil unless line =~ GATE_OPEN_RE
       # Preprocessor は #@since "1.8.5" のクォート形式も受理する
-      IncludeGraph::Condition.new($1.to_sym, $2.strip.delete_prefix('"').delete_suffix('"'))
+      IncludeGraph::Condition.new(($1 || raise).to_sym, ($2 || raise).strip.delete_prefix('"').delete_suffix('"'))
     end
 
     # i のゲート開始行から対応を取り、{body:, else_body:, next:} を返す。
     # body/else_body は枝の行列、next は #@end の次の行 index。対応が取れなければ nil
     def parse_block(lines, i)
       depth = 0
-      body = []
-      else_body = []
+      body = [] #: Array[String]
+      else_body = [] #: Array[String]
       current = body
       j = i
       while j < lines.length
@@ -213,7 +214,7 @@ def first_content_is_h1?(branch_lines)
 
     # i 以降の最初の非空行が H1 ならその名前を返す
     def first_h1_name(lines, i)
-      first = lines[i..].find { |l| l !~ BLANK_RE }
+      first = (lines[i..] || raise).find { |l| l !~ BLANK_RE }
       first =~ H1_RE ? $1 : nil
     end
   end

lib/bitclust/include_graph.rb

@@ -40,8 +40,8 @@ def self.interval(conditions)
     # 分解して境界に寄与させる。分解できない連言子は寄与しない（保守的に広く扱う。
     # 恒偽の証明は Scope#never? が連言子単位で別途行う）
     def self.bounds(conditions)
-      sinces = []
-      untils = []
+      sinces = [] #: Array[bound]
+      untils = [] #: Array[bound]
       conditions.each do |c|
         case c.kind
         when :since then sinces << [Gem::Version.new(c.version), c.version]
@@ -60,7 +60,7 @@ def self.bounds(conditions)
     # <= や否定（#@else 反転）は正確に表現できないので分解しない
     def self.if_bounds(expr)
       return [] if expr.lstrip.start_with?('!')
-      bounds = []
+      bounds = [] #: Array[[Symbol, String?]]
       expr.split(/\band\b/).each do |c|
         case c
         when /version\s*<\s*"([\d.]+)"/ then bounds << [:until, $1]
@@ -142,7 +142,7 @@ def never_conjunct?(conjunct)
       def gate(conditions)
         return nil unless cover?(conditions)
         lo, hi = IncludeGraph.bounds(conditions)
-        gate = {}
+        gate = {} #: IncludeGraph::gate
         gate[:since] = lo[1] if lo && lo[0] > @lo
         gate[:until] = hi[1] if hi && hi[0] < @hi
         gate
@@ -199,7 +199,7 @@ def grouping_include_sites
     # LIBRARIES 内の版ゲート（fiber: until 3.1 等）をスコープ適用して付与する。
     # スコープ外のライブラリ（cmath/scanf/sync 等）は含まない。
     def library_front_matter_map(scope)
-      result = {}
+      result = {} #: Hash[String, Hash[String, String]]
       @library_gates.each do |name, gate|
         root = "#{name}.rd"
         scoped = scope.gate(gate)
@@ -227,7 +227,7 @@ def library_front_matter_map(scope)
     # - 同一ライブラリ内の複数 include サイトは、いずれかが有効なら
     #   エンティティが存在するため、ゲートは区間の hull（弱い方）を取る
     def front_matter_map(scope)
-      result = {}
+      result = {} #: Hash[String, front_matter]
       groupings.each do |path, ms|
         covered = ms.select { |m| scope.cover?(m.conditions) }
         next if covered.empty?
@@ -264,16 +264,16 @@ def hull(gates)
       return {} if gates.any?(&:empty?)
       sinces = gates.map { |g| g[:since] }
       untils = gates.map { |g| g[:until] }
-      result = {}
+      result = {} #: gate
       result[:since] = sinces.min_by { |v| Gem::Version.new(v) } if sinces.all?
       result[:until] = untils.max_by { |v| Gem::Version.new(v) } if untils.all?
       result
     end
 
     # LIBRARIES を版ゲート付きで読む。 [[name, [Condition]], ...]
     def read_libraries
-      entries = {}
-      stack = []
+      entries = {} #: Hash[String, Array[Condition]]
+      stack = [] #: Array[Condition]
       File.foreach(File.join(@src_root, 'LIBRARIES')) do |line|
         line = line.chomp
         if line.start_with?('#@#') || apply_directive(stack, line)
@@ -292,7 +292,7 @@ def apply_directive(stack, line)
       case line
       when /\A\#@since\s+(\S+)/  then stack.push(Condition.new(:since, $1))
       when /\A\#@until\s+(\S+)/  then stack.push(Condition.new(:until, $1))
-      when /\A\#@if\s*(.*)/      then stack.push(Condition.new(:if, $1.strip))
+      when /\A\#@if\s*(.*)/      then stack.push(Condition.new(:if, ($1 || raise).strip))
       when /\A\#@samplecode\b/   then stack.push(Condition.new(:samplecode, nil))
       when /\A\#@else\b/         then (cond = stack.pop) && stack.push(invert(cond))
       when /\A\#@end\b/          then stack.pop
@@ -313,12 +313,12 @@ def invert(cond)
     # relpath のファイル内の #@include を条件スタック付きで走査する。
     # base_conditions は LIBRARIES ゲート＋ここまでの include 経路の条件。
     def walk(relpath, library, base_conditions, path_stack)
-      stack = []
+      stack = [] #: Array[Condition]
       File.foreach(File.join(@src_root, relpath)) do |line|
         line = line.chomp
         if line =~ /\A\#@include\s*\((.*?)\)/
           conditions = (base_conditions + stack).reject { |c| c.kind == :samplecode }
-          add_include(relpath, $1, library, conditions, path_stack)
+          add_include(relpath, $1 || raise, library, conditions, path_stack)
         else
           apply_directive(stack, line)
         end

lib/bitclust/include_pruner.rb

@@ -33,14 +33,14 @@ module IncludePruner
 
     def prune(src, targets)
       return src if targets.empty?
-      lookup = {}
+      lookup = {} #: Hash[String?, bool]
       targets.each { |t| lookup[t] = true }
 
       lines = src.lines
       nodes = catch(:unbalanced) { parse(lines) }
       return src if nodes.nil?
 
-      stream = []
+      stream = [] #: stream
       changed = emit(nodes, lookup, stream)
       return src unless changed
       tidy(stream).join
@@ -54,7 +54,7 @@ def parse(lines)
     end
 
     def parse_nodes(lines, i)
-      nodes = []
+      nodes = [] #: Array[node]
       while i < lines.length
         line = lines[i]
         if line =~ ELSE_RE || line =~ END_RE
@@ -63,7 +63,7 @@ def parse_nodes(lines, i)
           gate = line !~ CODE_OPEN_RE
           body, j = parse_nodes(lines, i + 1)
           else_line = nil
-          else_body = []
+          else_body = [] #: Array[node]
           if j < lines.length && lines[j] =~ ELSE_RE
             else_line = lines[j]
             else_body, j = parse_nodes(lines, j + 1)
@@ -96,9 +96,9 @@ def emit(nodes, lookup, stream)
     end
 
     def emit_block(block, lookup, stream)
-      body = []
+      body = [] #: stream
       body_changed = emit(block.body, lookup, body)
-      else_body = []
+      else_body = [] #: stream
       else_changed = block.else_line ? emit(block.else_body, lookup, else_body) : false
       changed = body_changed || else_changed
 
@@ -124,7 +124,7 @@ def blank_only?(stream)
     # REMOVED 番兵を取り除きつつ、除去痕の前後が空行同士なら1つに畳み、
     # 先頭に残った空行を削る
     def tidy(stream)
-      result = []
+      result = [] #: Array[String]
       pending = false
       stream.each do |item|
         if item.equal?(REMOVED)

lib/bitclust/markdown_bridge.rb

@@ -38,7 +38,7 @@ def self.build_doc(md_doc_root, out_doc_root)
       referenced = files.flat_map { |f|
         base = File.dirname(f)
         File.read(File.join(md_doc_root, f)).scan(/^\#@include\((?!(?:\.\.\/)+api\/)(.*?)\)/)
-            .map { |t| File.expand_path(base == '.' ? t[0] : File.join(base, t[0]), '/')
+            .map { |t| File.expand_path(base == '.' ? (t[0] || raise) : File.join(base, t[0] || raise), '/')
                            .delete_prefix('/') }
       }.to_h { |t| [t, true] }
 
@@ -135,7 +135,7 @@ def member_includes(libname, emitted)
         [reopen_only ? 1 : 0, path]
       end
       "\n" + sorted.map { |path|
-        m = members[path][:memberships].find { |mm| mm[:library] == libname }
+        m = members[path][:memberships].find { |mm| mm[:library] == libname } || raise
         inc = "\#@include(#{relative(emitted[path], base)})\n"
         inc = "\#@since #{m[:since]}\n#{inc}\#@end\n" if m[:since]
         inc = "\#@until #{m[:until]}\n#{inc}\#@end\n" if m[:until]
@@ -156,7 +156,7 @@ def rewrite_includes(rrd, md_file, emitted)
       return rrd unless rrd.include?('#@include')
       base = File.dirname(md_file)
       rrd.gsub(INCLUDE_RE) do
-        pre, target, post = $1, $2, $3
+        pre, target, post = $1, ($2 || raise), $3
         resolved = resolve(base, target, emitted)
         "#{pre}#{resolved ? relative(emitted[resolved], File.dirname(emitted[md_file])) : target}#{post}"
       end

lib/bitclust/markdown_orchestrator.rb

@@ -63,7 +63,7 @@ def units(relpath, rrd)
       dir = library ? relpath.sub(/\.rd\z/, '') : File.dirname(relpath)
       entity_fm =
         if library
-          fm = { 'library' => relpath.sub(/\.rd\z/, '') }
+          fm = { 'library' => relpath.sub(/\.rd\z/, '') } #: IncludeGraph::front_matter
           %w[since until].each { |k| fm[k] = front_matter[k] if front_matter[k] }
           fm
         else
@@ -74,15 +74,15 @@ def units(relpath, rrd)
       units = segments.map do |name, text|
         next Unit.new(output_path(relpath, front_matter), text, front_matter) if name.nil?   # 概要部
 
-        fm = entity_fm.dup
+        seg_fm = entity_fm.dup
         if (unwrapped = WholeFileGate.unwrap_for_scope(text, @scope))
           # エンティティセグメントのゲートは自身の存在ゲート → 常に front matter へ
           text = unwrapped[0]
-          merge_gate(fm, unwrapped[1])
+          merge_gate(seg_fm, unwrapped[1])
         end
         text = rewrite_includes(text, source_dir, dir)
         filename = "#{EntitySplitter.entity_filename(name)}.md"
-        Unit.new(dir == '.' ? filename : File.join(dir, filename), text, fm)
+        Unit.new(dir == '.' ? filename : File.join(dir, filename), text, seg_fm)
       end
       if library && segments.none? { |name, _| name.nil? }
         # 概要部が無くてもライブラリ自体が発見から消えないよう front matter のみ合成
@@ -145,7 +145,7 @@ def rewrite_includes(text, source_dir, new_dir)
       return text if source_dir == new_dir || text !~ /\#@include/
       base = File.expand_path(new_dir, '/')
       text.gsub(/^(\#@include\s*\()(.*?)(\))/) do
-        pre, target, post = $1, $2, $3
+        pre, target, post = $1, ($2 || raise), $3
         abs = File.expand_path(source_dir == '.' ? target : File.join(source_dir, target), '/')
         "#{pre}#{Pathname.new(abs).relative_path_from(base)}#{post}"
       end
@@ -182,25 +182,25 @@ def output_path(relpath, front_matter)
     # 関係を持たない H1 の直後や本文の空行・散文ゲートは触らない
     def normalize_header_regions(rrd)
       lines = rrd.lines
-      out = []
+      out = [] #: Array[String]
       i = 0
       while i < lines.length
         line = lines[i]
         out << line
         i += 1
         next unless line =~ EntitySplitter::H1_RE
-        region = []
+        region = [] #: Array[String]
         while i < lines.length &&
               (lines[i] =~ RELATION_RE || lines[i] =~ HEADER_DIR_RE || lines[i] =~ BLANK_LINE_RE)
           region << lines[i]
           i += 1
         end
         last_rel = region.rindex { |l| l =~ RELATION_RE }
         if last_rel
-          head = region[0..last_rel].reject { |l| l =~ BLANK_LINE_RE }
-                                    .map { |l| l =~ RELATION_RE ? "#{l.rstrip}\n" : l }
+          head = (region[0..last_rel] || raise).reject { |l| l =~ BLANK_LINE_RE }
+                                               .map { |l| l =~ RELATION_RE ? "#{l.rstrip}\n" : l }
           out.concat(head)
-          out.concat(region[(last_rel + 1)..])
+          out.concat(region[(last_rel + 1)..] || raise)
         else
           out.concat(region)
         end