bitclust-core 1.3.0 → 1.6.0

data/lib/bitclust/link_checker.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+#
+# bitclust/link_checker.rb
+#
+# DB 全体を走査して [[c:]]/[[m:]]/[[lib:]]/[[d:]]/[[f:]] 参照の
+# リンク切れを検出する。bitclust の参照リンクは描画時に存在検証されない
+# (URL を文字列変換で組むだけ)ため、壊れた参照は静かにリンク切れになる。
+#
+# 参照の抽出は正規表現の自前スキャンではなく、実際のコンパイル経路
+# (RDCompiler#bracket_link に仕込んだフック @option[:link_checker])で
+# 行う。これにより「描画時に本当にリンクになるものだけ」が対象になり、
+# コードスパン・コードフェンス内の参照風テキストは自然に除外される。
+
+require 'bitclust/compat'
+require 'bitclust/nameutils'
+require 'bitclust/methodid'
+require 'bitclust/exception'
+
+module BitClust
+
+  class LinkChecker
+
+    Finding = Struct.new(:location, :ref, :message)
+
+    # bracket_link が扱う型のうち、DB 外を指すので検証対象外のもの
+    EXTERNAL_TYPES = %w[url man rfc RFC ruby-list ruby-dev ruby-ext
+                        ruby-talk ruby-core feature bug misc].freeze
+
+    def initialize(db, function_database: nil)
+      @db = db
+      @fdb = function_database
+      @findings = [] #: Array[Finding]
+      @current_location = nil #: String?
+      @skipped_function_refs = 0
+    end
+
+    attr_reader :findings
+    attr_reader :skipped_function_refs
+    attr_accessor :current_location
+
+    def broken_count
+      @findings.size
+    end
+
+    # DB 中の全ソース(ライブラリ・クラス・メソッド・doc ページ)を
+    # コンパイルして findings を収集する
+    def check_all
+      @db.libraries.sort_by(&:id).each do |lib|
+        check_source(lib.source_location || "library #{lib.name}") {|c| c.compile(lib.source.to_s) }
+      end
+      @db.classes.sort_by(&:id).each do |klass|
+        check_source(klass.source_location || "class #{klass.name}") {|c| c.compile(klass.source.to_s) }
+        klass.entries.sort_by(&:id).each do |m|
+          check_source(m.source_location || "#{klass.name} #{m.name}") {|c| c.compile_method(m) }
+        end
+      end
+      @db.docs.sort_by(&:id).each do |doc|
+        check_source(doc.source_location || "doc #{doc.name}") {|c| c.compile(doc.source.to_s) }
+      end
+      @findings
+    end
+
+    # RDCompiler#bracket_link から呼ばれるフック。描画には影響しない
+    def note_ref(type, arg)
+      case type
+      when 'c'   then check_class(arg)
+      when 'm'   then check_method(arg)
+      when 'lib' then check_library(arg)
+      when 'd'   then check_doc(arg)
+      when 'f'   then check_function(arg)
+      when 'ref' then check_ref(arg)
+      else
+        unless EXTERNAL_TYPES.include?(type)
+          # 未知の型は bracket_link がリテラル [[...]] のまま出力する。
+          # ほぼ確実に型名の書き間違いなので報告する
+          record(type, arg, 'unknown link type')
+        end
+      end
+      nil
+    end
+
+    private
+
+    def check_source(location)
+      # Location#to_s は行番号不明のとき "path:" になるので末尾の : を落とす
+      @current_location = location.to_s.sub(/:\z/, '')
+      compiler = new_compiler
+      begin
+        yield compiler
+      rescue => err
+        # コンパイル自体の失敗はリンク切れとは別問題(構文エラー等)。
+        # チェックを止めず、報告だけして続行する
+        record('compile', location.to_s, "compile failed: #{err.class}: #{err.message}")
+      end
+    ensure
+      @current_location = nil
+    end
+
+    def new_compiler
+      mapper_conf = Hash.new {|_h, _k| '' } #: untyped
+      urlmapper = URLMapper.new(mapper_conf)
+      opt = { :database => @db, :link_checker => self } #: RDCompiler::option
+      if @db.properties['source_format'] == 'markdown'
+        require 'bitclust/mdcompiler'
+        gfm_opt = opt.merge(:gfm => true) #: RDCompiler::option
+        MDCompiler.new(urlmapper, 1, gfm_opt)
+      else
+        require 'bitclust/rdcompiler'
+        RDCompiler.new(urlmapper, 1, opt)
+      end
+    end
+
+    def check_class(name)
+      @db.fetch_class(name)
+    rescue NotFoundError, InvalidKey
+      record('c', name, 'class not found')
+    end
+
+    def check_method(spec_str)
+      # rdcompiler の complete_spec と同じ補完($~ 等は Kernel の特殊変数)
+      str = spec_str.start_with?('$') ? "Kernel#{spec_str}" : spec_str
+      begin
+        spec = MethodSpec.parse(str)
+      rescue => _err
+        record('m', spec_str, 'malformed method spec')
+        return
+      end
+      # fetch_methods は不在時に空配列(truthy)を返してしまい raise しない
+      # ため、単数形の fetch_method(不在で MethodNotFound)を使う
+      @db.fetch_method(spec)
+    rescue NotFoundError, InvalidKey
+      record('m', spec_str, 'method not found')
+    end
+
+    def check_library(name)
+      return if name == '/' || name == '_index'
+      @db.fetch_library(name)
+    rescue NotFoundError, InvalidKey
+      record('lib', name, 'library not found')
+    end
+
+    def check_doc(name)
+      @db.fetch_doc(name)
+    rescue NotFoundError, InvalidKey
+      record('d', name, 'doc not found')
+    end
+
+    def check_function(name)
+      return if name == '/' || name == '_index' || name.empty?
+      fdb = @fdb
+      unless fdb
+        @skipped_function_refs += 1
+        return
+      end
+      fdb.fetch_function(name)
+    rescue NotFoundError, InvalidKey
+      record('f', name, 'function not found')
+    end
+
+    # [[ref:type:name#frag]] 形式のみ検証する(参照先本体の存在チェック)。
+    # エントリローカルの [[ref:frag]] 形式は対象外(entry 文脈が必要で、
+    # アンカー未定義でも描画は劣化表示に留まるため)
+    def check_ref(arg)
+      if /\A(\w+):(.*)\#[-\w]+\z/ =~ arg
+        type, name = $1, $2
+        case type
+        when 'c'   then check_class(name || raise)
+        when 'm'   then check_method(name || raise)
+        when 'lib' then check_library(name || raise)
+        when 'd'   then check_doc(name || raise)
+        end
+      end
+    end
+
+    def record(type, arg, message)
+      @findings.push Finding.new(@current_location, "#{type}:#{arg}", message)
+    end
+  end
+end

data/lib/bitclust/markdown_bridge.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'pathname'
+
+require 'bitclust/markdown_tree'
+require 'bitclust/markdown_to_rrd'
+
+module BitClust
+  # md ツリー → 旧形式の rd ツリー（LIBRARIES + .rd）を生成するブリッジ。
+  #
+  # 既存の update 機構（LIBRARIES → RRDParser/Preprocessor）を一切変更せずに
+  # md ツリーから DB を組み立てるための変換層。MarkdownTree の発見結果から:
+  # - LIBRARIES を再生成（ライブラリの since/until は #@ ゲートとして再具現化）
+  # - ライブラリ .rd = 変換済み本文 + メンバーへの #@include を再生成
+  # - メンバー = 変換済み本文を front matter の since/until で #@ ラップ
+  #   （版指定ビルドで構造ゲートが効くように）
+  # - 断片 = そのまま変換
+  # 出力ファイル名は「md 名から .md を剥いだもの」（ライブラリのみ .rd 付き）に
+  # 統一し、本文中の #@include ターゲットも emit 名へ書き換える
+  # （Preprocessor はリテラルパスで解決するため）。
+  class MarkdownBridge
+    INCLUDE_RE = /^(\#@include\s*\()(.*?)(\))/
+
+    def self.build(md_root, out_root)
+      new(md_root, out_root).build
+    end
+
+    # doc（散文ページ）の md ツリー → 旧形式の doc/*.rd。
+    # - クロスツリー include（api 断片の transclude）は旧レイアウト
+    #   （../api/src/）へ戻す（ブリッジの api ツリーは api/src に置かれるため）
+    # - doc 内ローカル include から参照される断片（spec/regexp19 等）は
+    #   拡張子なしで emit する（copy_doc は **/*.rd だけをページとして読む）
+    # 戻り値は source_map（出力相対パス => 入力 md 相対パス）
+    def self.build_doc(md_doc_root, out_doc_root)
+      require 'bitclust/markdown_to_rrd'
+      files = Dir.glob('**/*.md', base: md_doc_root).sort
+      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] || raise) : File.join(base, t[0] || raise), '/')
+                           .delete_prefix('/') }
+      }.to_h { |t| [t, true] }
+
+      files.to_h do |f|
+        rrd = MarkdownToRRD.convert(File.read(File.join(md_doc_root, f)))
+        rrd = rrd.gsub(%r{^(\#@include\((?:\.\./)+api/)(?!src/)}, '\1src/')
+        name = f.sub(/\.md\z/, '')
+        rel = referenced[name] ? name : "#{name}.rd"
+        full = File.join(out_doc_root, rel)
+        FileUtils.mkdir_p(File.dirname(full))
+        File.write(full, rrd)
+        [rel, f]
+      end
+    end
+
+    attr_reader :warnings
+
+    # 出力相対パス（emit 名） => 入力 md 相対パス。
+    # source_location を manual/ の md へ再マップするために使う
+    attr_reader :source_map
+
+    def initialize(md_root, out_root)
+      @md_root = md_root
+      @out_root = out_root
+      @tree = MarkdownTree.scan(md_root)
+      @warnings = @tree.warnings.dup
+      @source_map = {}
+      # 名前はパス由来とは限らない（ファイル名衝突回避で改名された
+      # rdoc/rdoc.lib.md は front matter の name: が正）ので、パスから引く
+      @lib_by_path = @tree.libraries.to_h { |name, lib| [lib[:path], name] }
+    end
+
+    def build
+      files = Dir.glob('**/*.md', base: @md_root).sort
+      @dirs = files.flat_map { |f|
+        parts = File.dirname(f).split('/')
+        (1..parts.size).map { |n| parts.first(n).join('/') }
+      }.uniq - ['.']
+      emitted = files.to_h { |f| [f, emit_name(f)] }
+      @source_map = emitted.invert
+
+      files.each do |f|
+        rrd = MarkdownToRRD.convert(File.read(File.join(@md_root, f)))
+        rrd = rewrite_includes(rrd, f, emitted)
+        if (libname = @lib_by_path[f])
+          rrd << member_includes(libname, emitted)
+        elsif (entity = @tree.entities[f])
+          rrd = wrap_gate(rrd, entity)
+        end
+        write(emitted[f], rrd)
+      end
+      write('LIBRARIES', libraries_manifest)
+      self
+    end
+
+    private
+
+    # ライブラリは <name>.rd（update_by_stdlibtree の解決規約）。
+    # 非ライブラリは拡張子なし（doc ツリーが `../api/src/_builtin/pack-template` の
+    # ように元式の拡張子なし名で断片を transclude しているため）。
+    # ただし同名ディレクトリと衝突する場合は .rd を付ける（scanf.md と scanf/）
+    def emit_name(f)
+      return "#{@lib_by_path[f]}.rd" if @lib_by_path[f]
+      name = f.sub(/\.md\z/, '')
+      return "#{name}.rd" if @dirs.include?(name)
+      name
+    end
+
+    # LIBRARIES: 名前順。ライブラリの版ゲートは #@ で再具現化する
+    def libraries_manifest
+      @tree.libraries.sort.map { |name, lib|
+        entry = "#{name}\n"
+        entry = "\#@since #{lib[:since]}\n#{entry}\#@end\n" if lib[:since]
+        entry = "\#@until #{lib[:until]}\n#{entry}\#@end\n" if lib[:until]
+        entry
+      }.join
+    end
+
+    # ライブラリのメンバー（membership がこのライブラリを指すエンティティ）への
+    # #@include をライブラリ .rd のディレクトリ相対で再生成する。
+    # reopen/redefine だけのファイルは後ろに並べる（reopen が dynamic include する
+    # module は同ライブラリ内で先に定義されている必要がある: json/rake）。
+    # 多重所属（ゲート付き library リスト）は membership のゲートで
+    # include サイトをラップする（旧 LIBRARIES 世界のゲート付き include と同義）
+    def member_includes(libname, emitted)
+      base = File.dirname("#{libname}.rd")
+      members = @tree.entities.select { |path, e|
+        e[:memberships].any? { |m| m[:library] == libname }
+      }
+      return '' if members.empty?
+
+      sorted = members.keys.sort_by do |path|
+        reopen_only = members[path][:kinds].all? { |kind, _| %w[reopen redefine].include?(kind) }
+        [reopen_only ? 1 : 0, path]
+      end
+      "\n" + sorted.map { |path|
+        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]
+        inc
+      }.join
+    end
+
+    # front matter の構造ゲート（since/until）を #@ ラッパーとして再具現化する
+    def wrap_gate(rrd, entity)
+      rrd = "\#@since #{entity[:since]}\n#{rrd}\#@end\n" if entity[:since]
+      rrd = "\#@until #{entity[:until]}\n#{rrd}\#@end\n" if entity[:until]
+      rrd
+    end
+
+    # 本文中の #@include ターゲットを emit 名（相対）へ書き換える。
+    # 解決できないターゲットはそのまま（発見段階で警告済み）
+    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 || raise), $3
+        resolved = resolve(base, target, emitted)
+        "#{pre}#{resolved ? relative(emitted[resolved], File.dirname(emitted[md_file])) : target}#{post}"
+      end
+    end
+
+    def resolve(base, target, emitted)
+      [target, "#{target}.md", "#{target.sub(/\.rd\z/, '')}.md"].uniq.each do |cand|
+        rel = base == '.' ? cand : File.join(base, cand)
+        rel = File.expand_path(rel, '/').delete_prefix('/')
+        return rel if emitted.key?(rel)
+      end
+      nil
+    end
+
+    def relative(path, from_dir)
+      return path if from_dir == '.'
+      Pathname.new(File.expand_path(path, '/'))
+              .relative_path_from(File.expand_path(from_dir, '/')).to_s
+    end
+
+    def write(rel, content)
+      full = File.join(@out_root, rel)
+      FileUtils.mkdir_p(File.dirname(full))
+      File.write(full, content)
+    end
+  end
+end

data/lib/bitclust/markdown_orchestrator.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+require 'pathname'
+
+require 'bitclust/include_graph'
+require 'bitclust/rrd_to_markdown'
+require 'bitclust/include_pruner'
+require 'bitclust/whole_file_gate'
+require 'bitclust/entity_splitter'
+require 'bitclust/rrd_to_markdown'
+
+module BitClust
+  # RD ツリー → Markdown ツリー変換のクロスファイル方針を束ねるオーケストレータ。
+  #
+  # 単一ファイル記法変換（RRDToMarkdown）はそのままに、include グラフの解析結果から
+  # 各ファイルへ次を適用する:
+  # - grouping include の prune（エンティティ取り込みは front matter 発見へ移行）
+  # - ファイル全体を包む版ゲートの解除（front matter の since/until へ移行）
+  # - front matter 注入（member: library/構造ゲート、library ルート: type/版ゲート）
+  #
+  # スコープ（対象版範囲）はパラメータ。旧版サルベージ時は別スコープで再実行する。
+  class MarkdownOrchestrator
+    attr_reader :scope, :graph
+
+    def initialize(src_root, scope: IncludeGraph::Scope.new('3.0', '4.2'))
+      @graph = IncludeGraph.analyze(src_root)
+      @scope = scope
+      @extra = @graph.front_matter_map(scope)
+      @graph.library_front_matter_map(scope).each do |path, fm|
+        (@extra[path] ||= {}).merge!(fm)
+      end
+      @prune_sites = @graph.grouping_include_sites
+    end
+
+    def warnings
+      @graph.warnings
+    end
+
+    # 変換対象か。LIBRARIES は front matter による発見に置き換わるため対象外
+    def convert?(relpath)
+      relpath != 'LIBRARIES'
+    end
+
+    # 1つの出力 .md ファイルに対応する単位。
+    # path = 出力相対パス、rrd = rd 側到達点（md→rd 検証の期待値）、
+    # front_matter = 注入する front matter
+    Unit = Struct.new(:path, :rrd, :front_matter)
+
+    # relpath の RD を出力単位の列に還元する。
+    # ヘッダ関係（include/extend/alias）を持つマルチエンティティファイルは
+    # エンティティ単位に分割する（関係の front matter 一元化のため）。
+    # 関係を持たない束ね（Errno 族等）と lib+単一エンティティ兼用ファイルは
+    # 1 単位のまま。ライブラリファイルの分割ではエンティティを <libname>/ 配下に
+    # 置き、library と版ゲートを注入する
+    def units(relpath, rrd)
+      reduced, front_matter = reduce(relpath, rrd)
+      # スコープ外ファイル（front matter 注入なし）は分割しない。
+      # サルベージは別スコープの再実行で扱う
+      segments = front_matter.empty? ? nil : split_segments(reduced)
+      return [Unit.new(output_path(relpath, front_matter), reduced, front_matter)] unless segments
+
+      library = front_matter['type'] == 'library'
+      dir = library ? relpath.sub(/\.rd\z/, '') : File.dirname(relpath)
+      entity_fm =
+        if library
+          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
+          front_matter
+        end
+
+      source_dir = File.dirname(relpath)
+      units = segments.map do |name, text|
+        next Unit.new(output_path(relpath, front_matter), text, front_matter) if name.nil?   # 概要部
+
+        seg_fm = entity_fm.dup
+        if (unwrapped = WholeFileGate.unwrap_for_scope(text, @scope))
+          # エンティティセグメントのゲートは自身の存在ゲート → 常に front matter へ
+          text = unwrapped[0]
+          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, seg_fm)
+      end
+      if library && segments.none? { |name, _| name.nil? }
+        # 概要部が無くてもライブラリ自体が発見から消えないよう front matter のみ合成
+        units.unshift(Unit.new(output_path(relpath, front_matter), '', front_matter))
+      end
+      units
+    end
+
+    def convert_unit(unit)
+      RRDToMarkdown.convert(unit.rrd, extra_front_matter: unit.front_matter)
+    end
+
+    # relpath の RD を新パイプライン形の Markdown へ変換する（分割なしファイル用）
+    def convert(relpath, rrd)
+      us = units(relpath, rrd)
+      raise ArgumentError, "#{relpath} splits into #{us.size} files, use units" if us.size > 1
+      convert_unit(us.first)
+    end
+
+    # 変換の rd 側到達点（prune + 全体ゲート解除 + 定数 H1 ゲート解決後の RD）と
+    # front matter。MarkdownToRRD.convert(convert(...)) はこの RD と一致する
+    def reduce(relpath, rrd)
+      front_matter = (@extra[relpath] || {}).dup
+      rrd = IncludePruner.prune(rrd, @prune_sites[relpath] || [])
+      if (unwrapped = WholeFileGate.unwrap_for_scope(rrd, @scope))
+        if unwrap_allowed?(front_matter, unwrapped[1])
+          rrd = unwrapped[0]
+          merge_gate(front_matter, unwrapped[1])
+        elsif front_matter['type'] == 'library' &&
+              (regated = WholeFileGate.regate_metadata(rrd))
+          # 据え置きゲートの library ルート: メタデータ領域を独立ゲートに分離して
+          # front matter 化できるようにする（本文はゲートのまま）
+          rrd = regated
+        end
+      end
+      rrd = EntitySplitter.resolve_header_gates(rrd, @scope)
+      rrd = normalize_entity_h1(rrd)
+      rrd = normalize_signature_spacing(rrd)
+      rrd = RRDToMarkdown.normalize_dlist_colon_spacing(rrd)
+      rrd = rrd.sub(/\A(?:[ \t]*\n)+/, '')   # 先頭空行（ゲート解決の残り）を除去
+      [normalize_header_regions(rrd), front_matter]
+    end
+
+    private
+
+    # 分割すべきならセグメント列を、そうでなければ nil を返す。
+    # 条件: エンティティ（名前付きセグメント）が2つ以上 + いずれかがヘッダ関係を持つ。
+    # lib+単一エンティティ兼用（pathname 型、仕様が認める形）は分割しない
+    def split_segments(reduced)
+      return nil unless EntitySplitter.header_relations?(reduced)
+      segments = EntitySplitter.segments(reduced)
+      return nil unless segments
+      segments.count { |name, _| name } >= 2 ? segments : nil
+    end
+
+    # セグメントの置き場所が元ファイルと異なるディレクトリになる場合
+    # （lib 分割 → <libname>/ 配下）、相対 #@include を新ディレクトリから
+    # 解決できるよう書き換える
+    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 || raise), $3
+        abs = File.expand_path(source_dir == '.' ? target : File.join(source_dir, target), '/')
+        "#{pre}#{Pathname.new(abs).relative_path_from(base)}#{post}"
+      end
+    end
+
+    # 出力 .md の相対パス（.rd は差し替え、その他は付加）
+    def md_path(relpath)
+      relpath.end_with?('.rd') ? relpath.sub(/\.rd\z/, '.md') : "#{relpath}.md"
+    end
+
+    # ライブラリファイルの出力パス。他ファイルの出力と大文字小文字のみで
+    # 衝突する場合（rdoc/rdoc.md と rdoc/RDoc.md）は basename に .lib を挟んで
+    # 回避する（macOS/Windows の case-insensitive FS でチェックアウト不能に
+    # なるため）。名前がパスから導出できなくなるので front matter の name: で保持する
+    def output_path(relpath, front_matter)
+      path = md_path(relpath)
+      return path unless front_matter['type'] == 'library'
+      collides = @extra.keys.any? { |other|
+        next false if other == relpath
+        op = md_path(other)
+        op != path && op.casecmp?(path)
+      }
+      return path unless collides
+      front_matter['name'] = relpath.sub(/\.rd\z/, '')
+      path.sub(/\.md\z/, '.lib.md')
+    end
+
+    RELATION_RE = /\A(?:include|extend|alias)\s+\S/
+    HEADER_DIR_RE = /\A\#@(?:since|until|if|else|end)\b/
+    BLANK_LINE_RE = /\A\s*\z/
+
+    # H1 直後のヘッダ関係領域を md→rd の再生成形に正規化する:
+    # 最後の関係行までの空行を除き、関係行の末尾空白を落とす。
+    # 関係を持たない H1 の直後や本文の空行・散文ゲートは触らない
+    def normalize_header_regions(rrd)
+      lines = rrd.lines
+      out = [] #: Array[String]
+      i = 0
+      while i < lines.length
+        line = lines[i]
+        out << line
+        i += 1
+        next unless line =~ EntitySplitter::H1_RE
+        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] || 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)..] || raise)
+        else
+          out.concat(region)
+        end
+      end
+      out.join
+    end
+
+    # 「=class Encoding」のようなスペース無し H1（RRDParser は受理）を
+    # 正規形「= class」に直す。単一ファイル変換器は正規形のみ扱う
+    def normalize_entity_h1(rrd)
+      return rrd unless rrd =~ /^=(?:class|module|object|reopen|redefine)\b/
+      rrd.gsub(/^=((?:class|module|object|reopen|redefine)\b)/, '= \1')
+    end
+
+    # 「---critical=(bool)」のようなスペース無しシグネチャ（RDCompiler は
+    # /\A---/ で受理）を正規形「--- name」に直す。コードブロック内に
+    # 行頭 --- は現れない前提（roundtrip 検証が破れを検出する）
+    def normalize_signature_spacing(rrd)
+      rrd.gsub(/^---(?=[^\s-])/, '--- ')
+    end
+
+    # ファイル全体ゲートを front matter へ解除してよいか。
+    # - 常真ゲート（gate == {}）: 常に解除（従来どおり）
+    # - 断片・スコープ外（front matter なし）: 据え置き。front matter を付けると
+    #   #@include 展開の途中に `---` が現れてパースが壊れる（_builtin/Fiber.current）
+    # - type: library ルート: LIBRARIES 由来境界に包含される場合のみ（下記）
+    # - メンバー: エンティティ自身の存在ゲートなので常に解除
+    def unwrap_allowed?(front_matter, gate)
+      return true if gate.empty?
+      return false if front_matter.empty?
+      return true unless front_matter['type'] == 'library'
+      gate_subsumed?(front_matter, gate)
+    end
+
+    # ライブラリルートのファイル全体ゲートが LIBRARIES 由来の既存境界に
+    # 包含されるか。包含されないゲート（cmath: LIBRARIES は until のみ +
+    # ファイルは #@since 1.9.1）をマージすると「ライブラリの存在」まで
+    # 狭めてしまう（旧世界ではスコープ下限の版にも存在して内容が空）
+    def gate_subsumed?(front_matter, gate)
+      gate.all? { |kind, v|
+        cur = front_matter[kind.to_s]
+        next false unless cur
+        if kind == :since
+          Gem::Version.new(cur) >= Gem::Version.new(v)
+        else
+          Gem::Version.new(cur) <= Gem::Version.new(v)
+        end
+      }
+    end
+
+    # ファイル全体ゲートと注入済みゲート（include サイト / LIBRARIES 由来）の交差を取る
+    # （since は max、until は min。両者は同じ制約の別表現なので通常は一致する）
+    def merge_gate(front_matter, gate)
+      if (v = gate[:since])
+        front_matter['since'] = [front_matter['since'], v].compact
+                                  .max_by { |x| Gem::Version.new(x) }
+      end
+      if (v = gate[:until])
+        front_matter['until'] = [front_matter['until'], v].compact
+                                  .min_by { |x| Gem::Version.new(x) }
+      end
+    end
+  end
+end