rdoc 7.2.0 → 8.1.0

data/lib/rdoc/server.rb

@@ -0,0 +1,462 @@
+# frozen_string_literal: true
+
+require 'socket'
+require 'json'
+require 'erb'
+require 'set'
+require 'uri'
+
+module RDoc
+  ##
+  # A minimal HTTP server for live-reloading RDoc documentation.
+  #
+  # Uses Ruby's built-in +TCPServer+ (no external dependencies).
+  #
+  # Used by <tt>rdoc --server</tt> to let developers preview documentation
+  # while editing source files.  Parses sources once on startup, watches for
+  # file changes, re-parses only the changed files, and auto-refreshes the
+  # browser via a simple polling script.
+
+  class Server
+
+    ##
+    # Returns a live-reload polling script with the given +last_change_time+
+    # embedded so the browser knows the exact timestamp of the content it
+    # received.  This avoids a race where a change that occurs between page
+    # generation and the first poll would be silently skipped.
+
+    def self.live_reload_script(last_change_time)
+      <<~JS
+      <script>
+      (function() {
+        var lastChange = #{last_change_time.to_json};
+        setInterval(function() {
+          fetch('/__status').then(function(r) { return r.json(); }).then(function(data) {
+            if (data.last_change > lastChange) location.reload();
+            lastChange = data.last_change;
+          }).catch(function() {});
+        }, 1000);
+      })();
+      </script>
+    JS
+    end
+
+    CONTENT_TYPES = {
+      '.html' => 'text/html',
+      '.css'  => 'text/css',
+      '.js'   => 'application/javascript',
+      '.json' => 'application/json',
+    }.freeze
+
+    STATUS_TEXTS = {
+      200 => 'OK',
+      400 => 'Bad Request',
+      404 => 'Not Found',
+      405 => 'Method Not Allowed',
+      500 => 'Internal Server Error',
+    }.freeze
+
+    class FileChanges # :nodoc:
+      attr_reader :changed_files, :removed_files
+
+      def initialize(rdoc)
+        @rdoc = rdoc
+        @changed_files = []
+        @removed_files = []
+        @reload_rbs_signatures = false
+      end
+
+      def record_changed(file)
+        reload_rbs_signatures_if_needed file
+        changed_files << file
+      end
+
+      def record_removed(file)
+        reload_rbs_signatures_if_needed file
+        removed_files << file
+      end
+
+      def reload_rbs_signatures?
+        @reload_rbs_signatures
+      end
+
+      def source_files_changed?
+        !changed_files.empty? || !removed_files.empty?
+      end
+
+      private
+
+      def reload_rbs_signatures_if_needed(file)
+        @reload_rbs_signatures = true if @rdoc.auto_discovered_rbs_signature_file?(file)
+      end
+    end
+
+    ##
+    # Creates a new server.
+    #
+    # +rdoc+ is the RDoc::RDoc instance that has already parsed the source
+    # files.
+    # +port+ is the TCP port to listen on.
+
+    def initialize(rdoc, port)
+      @rdoc = rdoc
+      @options = rdoc.options
+      @store = rdoc.store
+      @port = port
+
+      # Silence stats output — the server prints its own timing.
+      @rdoc.stats.verbosity = 0
+      @generator = create_generator
+      @template_dir = File.expand_path(@generator.template_dir)
+      @page_cache = {}
+      @last_change_time = Time.now.to_f
+      @mutex = Mutex.new
+      @running = false
+    end
+
+    ##
+    # Starts the server.  Blocks until interrupted.
+
+    def start
+      @tcp_server = TCPServer.new('127.0.0.1', @port)
+      @running = true
+
+      @watcher_thread = start_watcher(@rdoc.watch_files)
+
+      url = "http://localhost:#{@port}"
+      $stderr.puts "\nServing documentation at: \e]8;;#{url}\e\\#{url}\e]8;;\e\\"
+      $stderr.puts "Press Ctrl+C to stop.\n\n"
+
+      loop do
+        client = @tcp_server.accept
+        Thread.new(client) { |c| handle_client(c) }
+      end
+    rescue Interrupt
+      # Ctrl+C
+    ensure
+      @running = false
+      @tcp_server&.close
+      @watcher_thread&.join(2)
+    end
+
+  private
+
+    def measure
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      yield
+      ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000).round(1)
+    end
+
+    def create_generator
+      gen = Generator::Aliki.new(@store, @options)
+      gen.file_output = false
+      gen.asset_rel_path = ''
+      gen.setup
+      gen
+    end
+
+    ##
+    # Reads an HTTP request from +client+ and dispatches to the router.
+
+    def handle_client(client)
+      client.binmode
+
+      return unless IO.select([client], nil, nil, 5)
+
+      request_line = client.gets("\n")
+      return unless request_line
+
+      method, request_uri, = request_line.split(' ', 3)
+      return write_response(client, 400, 'text/plain', 'Bad Request') unless request_uri
+
+      begin
+        path = URI.parse(request_uri).path
+      rescue URI::InvalidURIError
+        return write_response(client, 400, 'text/plain', 'Bad Request')
+      end
+
+      while (line = client.gets("\n"))
+        break if line.strip.empty?
+      end
+
+      unless method == 'GET'
+        return write_response(client, 405, 'text/plain', 'Method Not Allowed')
+      end
+
+      if path.start_with?('/__') || %r{\A/(?:css|js)/}.match?(path)
+        status, content_type, body = route(path)
+      else
+        duration_ms = measure do
+          status, content_type, body = route(path)
+        end
+        $stderr.puts "#{status} #{path} (#{duration_ms}ms)"
+      end
+      write_response(client, status, content_type, body)
+    rescue => e
+      write_response(client, 500, 'text/html', <<~HTML)
+      <!DOCTYPE html>
+      <html><body>
+      <h1>Internal Server Error</h1>
+      <pre>#{ERB::Util.html_escape e.message}\n#{ERB::Util.html_escape e.backtrace.join("\n")}</pre>
+      </body></html>
+    HTML
+    ensure
+      client.close rescue nil
+    end
+
+    ##
+    # Routes a request path and returns [status, content_type, body].
+
+    def route(path)
+      case path
+      when '/__status'
+        t = @mutex.synchronize { @last_change_time }
+        [200, 'application/json', JSON.generate(last_change: t)]
+      when '/js/search_data.js'
+        # Search data is dynamically generated, not a static asset
+        serve_page(path)
+      when %r{\A/(?:css|js)/}
+        serve_asset(path)
+      else
+        serve_page(path)
+      end
+    end
+
+    ##
+    # Writes an HTTP/1.1 response to +client+.
+
+    def write_response(client, status, content_type, body)
+      body_bytes = body.b
+
+      header = +"HTTP/1.1 #{status} #{STATUS_TEXTS[status] || 'Unknown'}\r\n"
+      header << "Content-Type: #{content_type}\r\n"
+      header << "Content-Length: #{body_bytes.bytesize}\r\n"
+      header << "Connection: close\r\n"
+      header << "\r\n"
+
+      client.write(header)
+      client.write(body_bytes)
+      client.flush
+    rescue Errno::EPIPE
+      # Client disconnected before we finished writing — harmless.
+    end
+
+    ##
+    # Serves a static asset (CSS, JS) from the Aliki template directory.
+
+    def serve_asset(path)
+      rel_path = path.delete_prefix("/")
+      asset_path = File.join(@generator.template_dir, rel_path)
+      real_asset = File.expand_path(asset_path)
+
+      unless real_asset.start_with?("#{@template_dir}/") && File.file?(real_asset)
+        return [404, 'text/plain', "Asset not found: #{rel_path}"]
+      end
+
+      ext = File.extname(rel_path)
+      content_type = CONTENT_TYPES[ext] || 'application/octet-stream'
+      [200, content_type, File.read(real_asset)]
+    end
+
+    ##
+    # Serves an HTML page, rendering from the generator or returning a cached
+    # version.
+
+    def serve_page(path)
+      name = path.delete_prefix("/")
+      name = 'index.html' if name.empty?
+
+      html = render_page(name)
+
+      unless html
+        not_found = @generator.generate_servlet_not_found(
+          "The page <kbd>#{ERB::Util.html_escape path}</kbd> was not found"
+        )
+        t = @mutex.synchronize { @last_change_time }
+        return [404, 'text/html', inject_live_reload(not_found || '', t)]
+      end
+
+      ext = File.extname(name)
+      content_type = CONTENT_TYPES[ext] || 'text/html'
+      [200, content_type, html]
+    end
+
+    ##
+    # Renders a page through the Aliki generator and caches the result.
+
+    def render_page(name)
+      @mutex.synchronize do
+        return @page_cache[name] if @page_cache[name]
+
+        result = generate_page(name)
+        return nil unless result
+
+        result = inject_live_reload(result, @last_change_time) if name.end_with?('.html')
+        @page_cache[name] = result
+      end
+    end
+
+    ##
+    # Dispatches to the appropriate generator method based on the page name.
+
+    def generate_page(name)
+      case name
+      when 'index.html'
+        @generator.generate_index
+      when 'table_of_contents.html'
+        @generator.generate_table_of_contents
+      when 'js/search_data.js'
+        "var search_data = #{JSON.generate(index: @generator.build_search_index)};"
+      else
+        text_name = name.chomp('.html')
+        class_name = text_name.gsub('/', '::')
+
+        if klass = @store.find_class_or_module(class_name)
+          @generator.generate_class(klass)
+        elsif page = @store.find_text_page(text_name.sub(/_([^_]*)\z/, '.\1'))
+          @generator.generate_page(page)
+        end
+      end
+    end
+
+    ##
+    # Injects the live-reload polling script before +</body>+.
+
+    def inject_live_reload(html, last_change_time)
+      html.sub('</body>', "#{self.class.live_reload_script(last_change_time)}</body>")
+    end
+
+    ##
+    # Starts a background thread that polls source file mtimes and triggers
+    # re-parsing when changes are detected.
+
+    def start_watcher(source_files)
+      @file_mtimes = file_mtimes_for(source_files)
+
+      Thread.new do
+        while @running
+          begin
+            sleep 1
+            check_for_changes
+          rescue => e
+            $stderr.puts "RDoc server watcher error: #{e.message}"
+          end
+        end
+      end
+    end
+
+    def file_mtimes_for(files)
+      files.each_with_object({}) do |f, h|
+        h[f] = ::RDoc.safe_mtime(f)
+      end
+    end
+
+    ##
+    # Checks for modified, new, and deleted files.  Returns true if any
+    # changes were found and processed.
+
+    def check_for_changes
+      changes = FileChanges.new @rdoc
+      current_files = current_watch_files
+      current_file_set = current_files.to_set
+
+      @file_mtimes.each_key do |file|
+        changes.record_removed file unless current_file_set.include? file
+      end
+
+      current_files.each do |file|
+        next unless file_changed? file
+
+        @file_mtimes[file] = nil unless @file_mtimes.key? file
+        changes.record_changed file
+      end
+
+      return false unless changes.source_files_changed?
+
+      reparse_and_refresh changes
+      true
+    end
+
+    ##
+    # Re-parses changed files, removes deleted files from the store,
+    # refreshes the generator, and invalidates caches.
+
+    def reparse_and_refresh(changes)
+      @mutex.synchronize do
+        remove_files changes.removed_files
+        reparse_files changes.changed_files
+        reload_rbs_signatures if changes.reload_rbs_signatures?
+        @store.complete(@options.visibility)
+        @store.invalidate_type_name_lookup if changes.source_files_changed?
+
+        @generator.refresh_store_data
+        @page_cache.clear
+        @last_change_time = Time.now.to_f
+      end
+    end
+
+    def current_watch_files
+      file_list = @rdoc.normalized_file_list(
+        @options.files.empty? ? [@options.root.to_s] : @options.files,
+        true, @options.exclude
+      )
+      @rdoc.remove_duplicate_files(@rdoc.remove_unparseable(file_list)).keys | @rdoc.auto_discovered_rbs_signature_files
+    end
+
+    def file_changed?(file)
+      return true unless @file_mtimes.key? file
+
+      old_mtime = @file_mtimes[file]
+      return true unless old_mtime
+
+      current_mtime = ::RDoc.safe_mtime(file)
+      current_mtime && current_mtime > old_mtime
+    end
+
+    def remove_files(files)
+      return if files.empty?
+
+      $stderr.puts "Removed: #{files.join(', ')}"
+      files.each do |f|
+        @file_mtimes.delete(f)
+        relative = @rdoc.relative_path_for(f)
+        @store.clear_file_contributions(relative)
+        @store.remove_file(relative)
+      end
+    end
+
+    def reload_rbs_signatures
+      duration_ms = measure do
+        @rdoc.load_auto_discovered_rbs_signatures
+        @rdoc.record_auto_discovered_rbs_signature_mtimes
+        @rdoc.auto_discovered_rbs_signature_files.each do |file|
+          @file_mtimes[file] = ::RDoc.safe_mtime(file)
+        end
+      end
+      $stderr.puts "Reloaded RBS signatures (#{duration_ms}ms)"
+    end
+
+    def reparse_files(files)
+      return if files.empty?
+
+      changed_file_names = []
+      duration_ms = measure do
+        files.each do |f|
+          relative = @rdoc.relative_path_for(f)
+          changed_file_names << relative
+          begin
+            @store.clear_file_contributions(relative, keep_position: true)
+            @rdoc.parse_file(f)
+            @file_mtimes[f] = ::RDoc.safe_mtime(f)
+          rescue => e
+            $stderr.puts "Error parsing #{f}: #{e.message}"
+          end
+        end
+
+        @store.cleanup_stale_contributions
+      end
+      $stderr.puts "Re-parsed #{changed_file_names.join(', ')} (#{duration_ms}ms)"
+    end
+
+  end
+end

data/lib/rdoc/stats/normal.rb

@@ -6,53 +6,57 @@ rescue LoadError
   require 'io/console'
 end
 
-##
-# Stats printer that prints just the files being documented with a progress
-# bar
+module RDoc
+  class Stats
+    ##
+    # Stats printer that prints just the files being documented with a progress
+    # bar
 
-class RDoc::Stats::Normal < RDoc::Stats::Quiet
+    class Normal < Stats::Quiet
 
-  def begin_adding # :nodoc:
-    puts "Parsing sources..."
-    @last_width = 0
-  end
+      def begin_adding # :nodoc:
+        puts "Parsing sources..."
+        @last_width = 0
+      end
 
-  ##
-  # Prints a file with a progress bar
-
-  def print_file(files_so_far, filename)
-    progress_bar = sprintf("%3d%% [%2d/%2d]  ",
-                           100 * files_so_far / @num_files,
-                           files_so_far,
-                           @num_files)
-
-    if $stdout.tty?
-      # Print a progress bar, but make sure it fits on a single line. Filename
-      # will be truncated if necessary.
-      size = IO.respond_to?(:console_size) ? IO.console_size : IO.console.winsize
-      terminal_width = size[1].to_i.nonzero? || 80
-      max_filename_size = (terminal_width - progress_bar.size) - 1
-
-      if filename.size > max_filename_size then
-        # Turn "some_long_filename.rb" to "...ong_filename.rb"
-        filename = filename[(filename.size - max_filename_size) .. -1]
-        filename[0..2] = "..."
+      ##
+      # Prints a file with a progress bar
+
+      def print_file(files_so_far, filename)
+        progress_bar = sprintf("%3d%% [%2d/%2d]  ",
+                               100 * files_so_far / @num_files,
+                               files_so_far,
+                               @num_files)
+
+        if $stdout.tty?
+          # Print a progress bar, but make sure it fits on a single line. Filename
+          # will be truncated if necessary.
+          size = IO.respond_to?(:console_size) ? IO.console_size : IO.console.winsize
+          terminal_width = size[1].to_i.nonzero? || 80
+          max_filename_size = (terminal_width - progress_bar.size) - 1
+
+          if filename.size > max_filename_size
+            # Turn "some_long_filename.rb" to "...ong_filename.rb"
+            filename = filename[(filename.size - max_filename_size) .. -1]
+            filename[0..2] = "..."
+          end
+
+          # Clean the line with whitespaces so that leftover output from the
+          # previous line doesn't show up.
+          $stdout.print("\r\e[K") if @last_width && @last_width > 0
+          @last_width = progress_bar.size + filename.size
+          term = "\r"
+        else
+          term = "\n"
+        end
+        $stdout.print(progress_bar, filename, term)
+        $stdout.flush
       end
 
-      # Clean the line with whitespaces so that leftover output from the
-      # previous line doesn't show up.
-      $stdout.print("\r\e[K") if @last_width && @last_width > 0
-      @last_width = progress_bar.size + filename.size
-      term = "\r"
-    else
-      term = "\n"
-    end
-    $stdout.print(progress_bar, filename, term)
-    $stdout.flush
-  end
+      def done_adding # :nodoc:
+        puts
+      end
 
-  def done_adding # :nodoc:
-    puts
+    end
   end
-
 end

data/lib/rdoc/stats/quiet.rb

@@ -1,59 +1,63 @@
 # frozen_string_literal: true
-##
-# Stats printer that prints nothing
+module RDoc
+  class Stats
+    ##
+    # Stats printer that prints nothing
 
-class RDoc::Stats::Quiet
+    class Quiet
 
-  ##
-  # Creates a new Quiet that will print nothing
+      ##
+      # Creates a new Quiet that will print nothing
 
-  def initialize(num_files)
-    @num_files = num_files
-  end
+      def initialize(num_files)
+        @num_files = num_files
+      end
 
-  ##
-  # Prints a message at the beginning of parsing
+      ##
+      # Prints a message at the beginning of parsing
 
-  def begin_adding(*) end
+      def begin_adding(*) end
 
-  ##
-  # Prints when an alias is added
+      ##
+      # Prints when an alias is added
 
-  def print_alias(*) end
+      def print_alias(*) end
 
-  ##
-  # Prints when an attribute is added
+      ##
+      # Prints when an attribute is added
 
-  def print_attribute(*) end
+      def print_attribute(*) end
 
-  ##
-  # Prints when a class is added
+      ##
+      # Prints when a class is added
 
-  def print_class(*) end
+      def print_class(*) end
 
-  ##
-  # Prints when a constant is added
+      ##
+      # Prints when a constant is added
 
-  def print_constant(*) end
+      def print_constant(*) end
 
-  ##
-  # Prints when a file is added
+      ##
+      # Prints when a file is added
 
-  def print_file(*) end
+      def print_file(*) end
 
-  ##
-  # Prints when a method is added
+      ##
+      # Prints when a method is added
 
-  def print_method(*) end
+      def print_method(*) end
 
-  ##
-  # Prints when a module is added
+      ##
+      # Prints when a module is added
 
-  def print_module(*) end
+      def print_module(*) end
 
-  ##
-  # Prints when RDoc is done
+      ##
+      # Prints when RDoc is done
 
-  def done_adding(*) end
+      def done_adding(*) end
 
+    end
+  end
 end