bitclust-core 1.2.6 → 1.6.0

data/lib/bitclust/subcommands/searchpage_command.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+#
+# bitclust/subcommands/searchpage_command.rb
+#
+# Generates a standalone, cross-version, client-side search page from
+# multiple version databases:
+#
+#   bitclust searchpage --outputdir=DIR db-3.0 db-3.1 ... db-4.1
+#
+# The output (index.html + js/search_data.js + assets) is fully static and
+# replaces the server-backed rurema-search app at docs.ruby-lang.org/ja/search/.
+# Each database's version is read from its own properties, and the merged
+# index tags every entry with the versions it appears in.
+#
+
+require 'pathname'
+require 'fileutils'
+require 'json'
+require 'optparse'
+
+require 'bitclust'
+require 'bitclust/subcommand'
+require 'bitclust/search_index_generator'
+
+module BitClust
+  module Subcommands
+    class SearchpageCommand < Subcommand
+      # search_init.js is the in-page dropdown wiring used by statichtml
+      # layouts; this page ships its own wiring (search_page.js) instead.
+      VENDORED_JS_FILES = %w[
+        search_navigation.js search_ranker.js search_controller.js
+      ].freeze
+
+      def initialize
+        super
+        @outputdir = nil
+        @themedir = srcdir_root + "theme/default"
+        @templatedir = srcdir_root + "data/bitclust/searchpage"
+        @suffix = ".html"
+        @fs_casesensitive = false
+        @verbose = false
+        @parser.banner = "Usage: #{File.basename($0, '.*')} searchpage [options] <dbpath>..."
+        @parser.on('-o', '--outputdir=PATH', 'Output directory.') {|path|
+          @outputdir = Pathname.new(path)
+        }
+        @parser.on('--themedir=PATH', 'Theme directory.') {|path|
+          @themedir = Pathname.new(path)
+        }
+        @parser.on('--fs-casesensitive', 'Filesystem is case-sensitive.') {
+          @fs_casesensitive = true
+        }
+        @parser.on('--verbose', 'Show progress.') {
+          @verbose = true
+        }
+      end
+
+      # DB paths are taken as positional arguments (one per version), so the
+      # global --database option is not required.
+      def needs_database?
+        false
+      end
+
+      def exec(argv, options)
+        outputdir = @outputdir or error("no --outputdir given")
+        error("no database given (pass one path per version)") if argv.empty?
+
+        generator = SearchIndexGenerator.new(suffix: @suffix,
+                                             fs_casesensitive: @fs_casesensitive)
+        version_indexes = argv.map {|path|
+          db = MethodDatabase.new(path)
+          fdb = FunctionDatabase.new(path) if File.directory?(File.join(path, 'function'))
+          version = db.properties['version'] or
+            error("#{path}: no version property (not a bitclust database?)")
+          $stderr.puts "indexing #{path} (#{version})" if @verbose
+          [version, generator.build_index(db, fdb)] #: [String, Array[SearchIndexGenerator::entry]]
+        }
+        versions = version_indexes.map {|version, _| version }
+                                  .sort_by {|v| Gem::Version.new(v) }
+
+        jsdir = outputdir + "js"
+        FileUtils.mkdir_p(jsdir)
+        (jsdir + "search_data.js").write(SearchIndexGenerator.merged_js(version_indexes))
+        VENDORED_JS_FILES.each do |js|
+          FileUtils.cp(@themedir + "js" + js, jsdir.to_s, :preserve => true)
+        end
+        # Ship the MIT notice for the vendored Aliki files alongside them.
+        FileUtils.cp(@themedir + "js" + "NOTICE", jsdir.to_s, :preserve => true)
+        FileUtils.cp(@themedir + "js" + "search_page.js", jsdir.to_s, :preserve => true)
+        FileUtils.cp(@themedir + "search.css", outputdir.to_s, :preserve => true)
+        (outputdir + "index.html").write(render_page(versions))
+        $stderr.puts "generated search page for #{versions.join(', ')}" if @verbose
+      end
+
+      private
+
+      def render_page(versions)
+        template = (@templatedir + "index.html").read
+        template.sub('%%SEARCH_VERSIONS%%', JSON.generate(versions))
+      end
+    end
+  end
+end

data/lib/bitclust/subcommands/server_command.rb

@@ -1,10 +1,10 @@
+# frozen_string_literal: true
 require 'pathname'
 require 'erb'
 require 'find'
 require 'pp'
 require 'optparse'
 require 'yaml'
-require 'webrick'
 require 'uri'
 
 require 'bitclust'
@@ -15,7 +15,6 @@ module BitClust
     class ServerCommand < Subcommand
       def initialize
         super
-        require 'webrick'
         require 'uri'
 
         @params = {
@@ -108,15 +107,20 @@ module BitClust
           exit 1
         end
         if @pid_file
-          if File.exist?(@pid_file)
+          if File.exist?(@pid_file || raise)
             $stderr.puts "There is still #{@pid_file}.  Is another process running?"
             exit 1
           end
-          @pid_file = File.expand_path(@pid_file)
+          @pid_file = File.expand_path(@pid_file || raise)
         end
       end
 
       def exec(argv, options)
+        begin
+          require 'webrick'
+        rescue LoadError
+          abort "webrick is not found. You may need to `gem install webrick` to install webrick."
+        end
         require 'bitclust/app'
         if @debugp
           @params[:Logger] = WEBrick::Log.new($stderr, WEBrick::Log::DEBUG)
@@ -129,7 +133,7 @@ module BitClust
           @params[:Logger] = WEBrick::Log.new($stderr, WEBrick::Log::INFO)
           @params[:AccessLog] = []
         end
-        basepath = URI.parse(@baseurl).path
+        basepath = URI.parse(@baseurl || raise).path or raise
         server = WEBrick::HTTPServer.new(@params)
 
         if @autop
@@ -168,17 +172,19 @@ module BitClust
         server.mount File.join(basepath, 'theme/'), WEBrick::HTTPServlet::FileHandler, @themedir
 
         if @debugp
-          trap(:INT) { server.shutdown }
+          Signal.trap(:INT) { server.shutdown }
         else
           WEBrick::Daemon.start do
-            trap(:TERM) {
+            Signal.trap(:TERM) {
               server.shutdown
               begin
-                File.unlink @pid_file if @pid_file
+                pid_file = @pid_file
+                File.unlink pid_file if pid_file
               rescue Errno::ENOENT
               end
             }
-            File.open(@pid_file, 'w') {|f| f.write Process.pid } if @pid_file
+            pid_file = @pid_file
+            File.open(pid_file, 'w') {|f| f.write Process.pid } if pid_file
           end
         end
         exit if $".include?("exerb/mkexy.rb")
@@ -205,7 +211,7 @@ module BitClust
       end
 
       def load_config_file
-        home_directory = Pathname(ENV['HOME'])
+        home_directory = Pathname(ENV.fetch('HOME'))
         config_path = home_directory + ".bitclust/config"
         if config_path.exist?
           config = YAML.load_file(config_path)

data/lib/bitclust/subcommands/setup_command.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require 'pathname'
 require 'erb'
 require 'find'
@@ -19,7 +20,7 @@ module BitClust
         @prepare = nil
         @cleanup = nil
         @purge = nil
-        @versions = ["2.4.0", "2.5.0", "2.6.0"]
+        @versions = ["3.3.0", "3.4.0", "4.0.0"]
         @update = true
         @parser.banner = "Usage: #{File.basename($0, '.*')} setup [options]"
         @parser.on('--prepare', 'Prepare config file and checkout repository. Do not create database.') {
@@ -39,6 +40,11 @@ module BitClust
         }
       end
 
+      # DB は ~/.bitclust 配下に自前で作るのでグローバル --database は不要
+      def needs_database?
+        false
+      end
+
       def exec(argv, options)
         purge if @purge
         prepare
@@ -48,18 +54,18 @@ module BitClust
           prefix = "#{@config[:database_prefix]}-#{version}"
           FileUtils.rm_rf(prefix) if @cleanup
           init_argv = ["version=#{version}", "encoding=#{@config[:encoding]}"]
-          init_options = { :prefix => prefix }
+          # @type var init_options: Subcommand::options
+          init_options = { :prefix => prefix, :capi => false }
           InitCommand.new.exec(init_argv, init_options)
-          update_method_database(prefix, ["--stdlibtree=#{@config[:stdlibtree]}"])
-          update_argv = Pathname(@config[:capi_src]).children.select(&:file?).map{|v| v.realpath.to_s }
-          update_function_database(prefix, update_argv)
+          update_method_database(prefix, ["--markdowntree=#{@config[:mdtree]}"])
+          update_function_database(prefix, ["--markdowntree=#{@config[:capi_mdtree]}"])
         end
       end
 
       private
 
       def purge
-        home_directory = Pathname(ENV["HOME"])
+        home_directory = Pathname(ENV.fetch("HOME"))
         config_dir = home_directory + ".bitclust"
         print "Remove all generated files..."
         FileUtils.rm_rf(config_dir.to_s)
@@ -68,7 +74,7 @@ module BitClust
       end
 
       def prepare
-        home_directory = Pathname(ENV["HOME"]).expand_path
+        home_directory = Pathname(ENV.fetch("HOME")).expand_path
         config_dir = home_directory + ".bitclust"
         config_dir.mkpath
         config_path = config_dir + "config"
@@ -78,17 +84,24 @@ module BitClust
           :encoding        => "utf-8",
           :versions        => @versions,
           :default_version => @versions.max,
-          :stdlibtree      => (rubydoc_dir + "refm/api/src").to_s,
-          :capi_src        => (rubydoc_dir + "refm/capi/src/").to_s,
+          :mdtree          => (rubydoc_dir + "manual/api").to_s,
+          :capi_mdtree     => (rubydoc_dir + "manual/capi").to_s,
           :baseurl         => "http://localhost:10080",
           :port            => "10080",
           :pid_file        => "/tmp/bitclust.pid",
         }
         if config_path.exist?
           @config = YAML.load_file(config_path)
+          unless @config[:mdtree]
+            # Markdown 移行(2026-07)前の設定ファイル。ソースの取得形態が
+            # 変わっているため、作り直しを案内する
+            warn "Old config file (before the Markdown migration) found: #{config_path}"
+            warn "Run `#{File.basename($0, '.*')} setup --purge` and setup again."
+            exit 1
+          end
           unless @config[:versions].sort == @versions.sort
             print("overwrite config file? > [y/N]")
-            if /\Ay\z/i =~ $stdin.gets.chomp
+            if /\Ay\z/i =~ $stdin.gets&.chomp
               @config[:versions] = @versions
               @config[:default_version] = @versions.max
               generate_config(config_path, @config)
@@ -131,6 +144,7 @@ module BitClust
       end
 
       def update_method_database(prefix, argv)
+        # @type var options: Subcommand::options
         options = {
           :prefix => prefix,
           :capi => false,
@@ -141,6 +155,7 @@ module BitClust
       end
 
       def update_function_database(prefix, argv)
+        # @type var options: Subcommand::options
         options = {
           :prefix => prefix,
           :capi => true,

data/lib/bitclust/subcommands/statichtml_command.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 # Copyright (c) 2006-2007 Minero Aoki
 #
 # This program is free software.
@@ -11,6 +12,7 @@ require 'bitclust/nameutils'
 require 'bitclust/subcommand'
 require 'bitclust/progress_bar'
 require 'bitclust/silent_progress_bar'
+require 'bitclust/search_index_generator'
 
 module BitClust
   module Subcommands
@@ -44,7 +46,7 @@ module BitClust
         end
 
         def method_url(spec)
-          cname, tmark, mname = *split_method_spec(spec)
+          cname, tmark, mname = split_method_spec(spec)
           filename = html_filename(encodename_package(mname), @suffix)
           @bitclust_html_base +
             "/method/#{encodename_package(cname)}/#{typemark2char(tmark)}/#{filename}"
@@ -89,7 +91,7 @@ module BitClust
         end
 
         def edit_url(location)
-          "#{@edit_base_url}/#{location.file}#L#{location.line}".sub(/([^:])\/\/+/, "\\1/")
+          "#{@edit_base_url}/#{location.file}".sub(/([^:])\/\/+/, "\\1/")
         end
 
         def encodename_package(str)
@@ -119,6 +121,10 @@ module BitClust
         @gtm_tracking_id = nil
         @meta_robots_content = ["noindex"]
         @stop_on_syntax_error = true
+        @eol_warning = false
+        @run_ruby_wasm = nil
+        @sitemap_baseurl = nil
+        @sitemap_paths = []
         @parser.banner = "Usage: #{File.basename($0, '.*')} statichtml [options]"
         @parser.on('-o', '--outputdir=PATH', 'Output directory') do |path|
           begin
@@ -155,6 +161,15 @@ module BitClust
         @parser.on('--meta-robots-content=VALUE1,VALUE2,...', Array, 'HTML <meta> element: <meta name="robots" content="VALUE1,VALUE2..."') do |values|
           @meta_robots_content = values
         end
+        @parser.on('--[no-]eol-warning', 'Show a warning banner that this Ruby version is no longer maintained') do |boolean|
+          @eol_warning = boolean
+        end
+        @parser.on('--run-ruby-wasm=WASM_URL', 'Add a RUN button to Ruby sample code, executing it in-browser with the given ruby.wasm') do |url|
+          @run_ruby_wasm = url
+        end
+        @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('--no-stop-on-syntax-error', 'Do not stop on syntax error') do |boolean|
           @stop_on_syntax_error = boolean
         end
@@ -172,8 +187,10 @@ module BitClust
         manager = ScreenManager.new(@manager_config)
 
         db.transaction do
-          methods = {}
+          methods = {} #: Hash[String, Array[MethodEntry]]
           db.methods.each_with_index do |entry, i|
+            next if entry.undefined?
+
             entry.names.each do |name|
               method_name = entry.klass.name + entry.typemark + name
               (methods[method_name] ||= []) << entry
@@ -190,22 +207,33 @@ module BitClust
         end
 
         @urlmapper.bitclust_html_base = '..'
-        create_file(@outputdir + "library/#{html_filename("index", @suffix)}",
+        library_index_path = @outputdir + "library/#{html_filename("index", @suffix)}"
+        create_file(library_index_path,
                     manager.library_index_screen(db.libraries.sort, {:database => db}).body,
                     :verbose => @verbose)
-        create_file(@outputdir + "class/#{html_filename("index", @suffix)}",
+        record_sitemap_path(library_index_path)
+        class_index_path = @outputdir + "class/#{html_filename("index", @suffix)}"
+        create_file(class_index_path,
                     manager.class_index_screen(db.classes.sort, {:database => db}).body,
                     :verbose => @verbose)
-        create_file(@outputdir + "function/#{html_filename("index", @suffix)}",
+        record_sitemap_path(class_index_path)
+        function_index_path = @outputdir + "function/#{html_filename("index", @suffix)}"
+        create_file(function_index_path,
                     manager.function_index_screen(fdb.functions.sort, { :database => fdb }).body,
                     :verbose => @verbose)
+        record_sitemap_path(function_index_path)
         create_index_html(@outputdir)
+        create_search_index(@outputdir, db, fdb)
+        if baseurl = @sitemap_baseurl
+          create_sitemap(@outputdir, baseurl)
+        end
         FileUtils.cp(@manager_config[:themedir] + @manager_config[:css_url],
                      @outputdir.to_s, :verbose => @verbose, :preserve => true)
         FileUtils.cp(@manager_config[:themedir] + "syntax-highlight.css",
                      @outputdir.to_s, :verbose => @verbose, :preserve => true)
         FileUtils.cp(@manager_config[:themedir] + "script.js",
                      @outputdir.to_s, :verbose => @verbose, :preserve => true)
+        copy_run_ruby_wasm_script if @run_ruby_wasm
         FileUtils.cp(@manager_config[:themedir] + @manager_config[:favicon_url],
                      @outputdir.to_s, :verbose => @verbose, :preserve => true)
         Dir.mktmpdir do |tmpdir|
@@ -237,6 +265,8 @@ module BitClust
           :gtm_tracking_id => @gtm_tracking_id,
           :meta_robots_content => @meta_robots_content,
           :stop_on_syntax_error => @stop_on_syntax_error,
+          :eol_warning => @eol_warning,
+          :run_ruby_wasm => @run_ruby_wasm,
         }
         @manager_config[:urlmapper] = URLMapperEx.new(@manager_config)
         @urlmapper = @manager_config[:urlmapper]
@@ -287,6 +317,101 @@ HERE
         }
       end
 
+      SEARCH_JS_FILES = %w[
+        search_navigation.js search_ranker.js search_controller.js search_init.js
+      ].freeze
+
+      def create_search_index(outputdir, db, fdb)
+        generator = SearchIndexGenerator.new(suffix: @suffix,
+                                             fs_casesensitive: @fs_casesensitive)
+        jsdir = outputdir + "js"
+        FileUtils.mkdir_p(jsdir) unless jsdir.directory?
+        create_file(jsdir + "search_data.js",
+                    generator.to_js(db, fdb),
+                    :verbose => @verbose)
+        themedir = @manager_config[:themedir]
+        SEARCH_JS_FILES.each do |js|
+          FileUtils.cp(themedir + "js" + js, jsdir.to_s,
+                       :verbose => @verbose, :preserve => true)
+        end
+        # Ship the MIT notice for the vendored Aliki files alongside them.
+        FileUtils.cp(themedir + "js" + "NOTICE", jsdir.to_s,
+                     :verbose => @verbose, :preserve => true)
+        FileUtils.cp(themedir + "search.css", outputdir.to_s,
+                     :verbose => @verbose, :preserve => true)
+      end
+
+      # A single sitemap.xml file supports at most 50,000 URLs
+      # (https://www.sitemaps.org/protocol.html#index). Splitting into a
+      # sitemap index is out of scope for now (small start); if the site
+      # grows past this, only the first MAX_SITEMAP_URLS pages are listed
+      # and a warning is printed.
+      MAX_SITEMAP_URLS = 50_000
+
+      # The 5 characters that need escaping to embed arbitrary text as XML
+      # character data (used for the <loc> contents below).
+      XML_ESCAPES = {
+        '&' => '&amp;',
+        '<' => '&lt;',
+        '>' => '&gt;',
+        '"' => '&quot;',
+        "'" => '&apos;',
+      }.freeze
+
+      def escape_xml(str)
+        str.gsub(/[&<>"']/) {|c| XML_ESCAPES.fetch(c) }
+      end
+
+      # Remember +path+ (an HTML page actually written under @outputdir) so
+      # that create_sitemap can list it later. A no-op unless
+      # --sitemap-baseurl was given, so sitemap generation has no effect on
+      # the rest of the run when the option is not used.
+      def record_sitemap_path(path)
+        return unless @sitemap_baseurl
+        @sitemap_paths << path.relative_path_from(@outputdir).to_s
+      end
+
+      # Generate outputdir/sitemap.xml: a plain XML sitemap
+      # (https://www.sitemaps.org/protocol.html) listing every page
+      # recorded via record_sitemap_path, as baseurl + relative path.
+      def create_sitemap(outputdir, baseurl)
+        paths = @sitemap_paths
+        if paths.size > MAX_SITEMAP_URLS
+          $stderr.puts "warning: #{paths.size} pages found, but a single sitemap.xml supports at most #{MAX_SITEMAP_URLS} URLs; only the first #{MAX_SITEMAP_URLS} are included. Consider a sitemap index if you need the rest."
+          paths = paths.first(MAX_SITEMAP_URLS)
+        end
+        base = baseurl.end_with?('/') ? baseurl : "#{baseurl}/"
+        xml = +%(<?xml version="1.0" encoding="UTF-8"?>\n)
+        xml << %(<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n)
+        paths.each do |path|
+          xml << "<url><loc>#{escape_xml(base + path)}</loc></url>\n"
+        end
+        xml << "</urlset>\n"
+        create_file(outputdir + "sitemap.xml", xml, :verbose => @verbose)
+      end
+
+      # Scripts for the RUN-button feature (statichtml --run-ruby-wasm):
+      # run.js sets up the button and compiles the wasm module on the main
+      # thread; run-worker.js is the module Worker it spawns per execution
+      # (see theme/default/js/run.js for why: STOP/timeout both just
+      # Worker#terminate() it). Both are required for the feature to work.
+      RUN_RUBY_WASM_JS_FILES = %w[run.js run-worker.js].freeze
+
+      # Copy the RUN-button scripts. A themedir missing one of them is
+      # tolerated: warn and skip instead of aborting the whole build.
+      def copy_run_ruby_wasm_script
+        jsdir = @outputdir + "js"
+        RUN_RUBY_WASM_JS_FILES.each do |name|
+          src = @manager_config[:themedir] + "js" + name
+          unless src.file?
+            $stderr.puts "warning: #{src} not found; RUN button script not copied"
+            next
+          end
+          FileUtils.mkdir_p(jsdir) unless jsdir.directory?
+          FileUtils.cp(src.to_s, jsdir.to_s, :verbose => @verbose, :preserve => true)
+        end
+      end
+
       def create_html_file(entry, manager, outputdir, db)
         e = entry.is_a?(Array) ? entry.sort.first : entry
         case e.type_id
@@ -325,6 +450,7 @@ HERE
         path.open('w') do |f|
           f.write(html)
         end
+        record_sitemap_path(path)
       end
 
       def create_file(path, str, options = {})

data/lib/bitclust/subcommands/update_command.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require 'pathname'
 require 'erb'
 require 'find'
@@ -15,11 +16,15 @@ module BitClust
       def initialize
         super
         @root = nil
+        @markdowntree = nil
         @library = nil
         @parser.banner = "Usage: #{File.basename($0, '.*')} update [<file>...]"
         @parser.on('--stdlibtree=ROOT', 'Process stdlib source directory tree.') {|path|
           @root = path
         }
+        @parser.on('--markdowntree=ROOT', 'Process Markdown source directory tree.') {|path|
+          @markdowntree = path
+        }
         @parser.on('--library-name=NAME', 'Use NAME for library name in file mode.') {|name|
           @library = name
         }
@@ -27,25 +32,129 @@ module BitClust
 
       def parse(argv)
         super
-        if not @root and argv.empty?
+        if not @root and not @markdowntree and argv.empty?
           error "no input file given"
         end
       end
 
       def exec(argv, options)
         super
+        if @markdowntree
+          # ネイティブ md パース（M3）。source には md が入り、描画は
+          # MDCompiler（GFM）が選択される。ブリッジは検証用に温存
+          # （BITCLUST_MD_BRIDGE=1 で旧経路）
+          if ENV['BITCLUST_MD_BRIDGE'] == '1'
+            argv = @db.is_a?(FunctionDatabase) ? prepare_capi_markdowntree
+                                               : (prepare_markdowntree; argv)
+          else
+            @db.transaction {
+              @db.update_by_markdowntree(@markdowntree || raise)
+            }
+            return
+          end
+        end
         @db.transaction {
           if @root
-            @db.update_by_stdlibtree @root
+            db = @db
+            db.is_a?(MethodDatabase) or raise
+            db.update_by_stdlibtree(@root || raise)
           end
           argv.each do |path|
             @db.update_by_file path, @library || guess_library_name(path)
           end
         }
+        remap_source_locations if @markdowntree
+      ensure
+        FileUtils.remove_entry(@bridge_dir) if @bridge_dir
       end
 
       private
 
+      # Markdown ツリーを旧形式の rd ツリーへブリッジし、既存の
+      # stdlibtree 更新機構にそのまま渡す。
+      # doc（散文ページ）は stdlibtree/../../doc から読まれるため、
+      # md ツリー側に doc/ が同居していればレイアウトを合わせる
+      # （manual/api を渡すと manual/doc を拾う。md ならブリッジ変換、
+      # .rd のまま（移行中）なら symlink）。
+      def prepare_markdowntree
+        require 'tmpdir'
+        require 'bitclust/markdown_bridge'
+        @bridge_dir = Dir.mktmpdir('bitclust-md-bridge')
+        root = File.join(@bridge_dir, 'api/src')
+        bridge = MarkdownBridge.build(@markdowntree || raise, root)
+        @location_map = { root => [@markdowntree, bridge.source_map] }
+        # markdowntree と同じ渡され方（相対/絶対）を保った隣接 doc パス。
+        # copy_doc は stdlibtree 相対（../../doc/...）の location を記録する
+        doc = File.join(File.dirname(@markdowntree || raise), 'doc')
+        if File.directory?(doc)
+          if Dir.glob(File.join(doc, '**/*.md')).any?
+            doc_map = MarkdownBridge.build_doc(doc, File.join(@bridge_dir, 'doc'))
+          else
+            FileUtils.ln_s(File.expand_path(doc), File.join(@bridge_dir, 'doc'))
+            doc_map = nil
+          end
+          @location_map[File.join(@bridge_dir, 'doc')] = [doc, doc_map]
+          @location_map['../../doc'] = [doc, doc_map]
+        end
+        @root ||= root
+      end
+
+      # C API の Markdown ツリー（manual/capi）を旧形式の .rd 群へ変換し、
+      # ファイル引数として返す（--capi update <files> の経路に載せる）
+      def prepare_capi_markdowntree
+        require 'tmpdir'
+        require 'bitclust/markdown_to_rrd'
+        @bridge_dir = Dir.mktmpdir('bitclust-capi-bridge')
+        # src/ 配下に置く: guess_library_name が src/ 以降を id とするため
+        # （関数の filename が旧経路と同じ「eval.c」等になる）
+        src = File.join(@bridge_dir, 'src')
+        FileUtils.mkdir_p(src)
+        capi_map = {} #: Hash[String, String]
+        files = Dir.glob(File.join(@markdowntree || raise, '*.md')).sort.map do |f|
+          name = "#{File.basename(f, '.md')}.rd"
+          rd = File.join(src, name)
+          File.write(rd, MarkdownToRRD.convert(File.read(f), capi: true))
+          capi_map[name] = "#{File.basename(f, '.md')}.md"
+          rd
+        end
+        @location_map = { src => [@markdowntree, capi_map] }
+        files
+      end
+
+      # source_location のブリッジ一時パスを manual/ の md パスへ再マップする。
+      # 編集リンク（statichtml --edit-base-url）が凍結 refm でなく編集対象の
+      # md を指すようにするため。行番号はブリッジ rd 基準の近似で、
+      # front matter 等の分だけ md とずれることがある
+      def remap_source_locations
+        db = @db
+        entries =
+          if db.is_a?(FunctionDatabase)
+            db.functions
+          else
+            db.is_a?(MethodDatabase) or raise
+            db.libraries + db.classes + db.methods + db.docs
+          end
+        entries.each do |entry|
+          loc = entry.source_location or next
+          remapped = remap_location(loc) or next
+          entry.source_location = remapped
+          entry.save
+        end
+      end
+
+      def remap_location(loc)
+        file = loc.file
+        file.is_a?(String) or raise
+        @location_map.each do |bridge_root, (md_root, map)|
+          prefix = "#{bridge_root}/"
+          next unless file.start_with?(prefix)
+          rel = file.delete_prefix(prefix)
+          rel = map[rel] || rel if map
+          return Location.new(File.join(md_root, rel), loc.line)
+        end
+        nil
+      end
+
       def guess_library_name(path)
         if %r<(\A|/)src/> =~ path
           path.sub(%r<.*(\A|/)src/>, '').sub(/\.rd\z/, '')