Track RBS sig file freshness, propagate to aliases, separate singleton attr keys

Three fixes for `merge_rbs_signatures` and the surrounding freshness flow:

- `rdoc.rb` now records `sig/*.rbs` mtimes alongside Ruby files in
  `@last_modified` and forces a full reparse when only signatures
  changed. The cached HTML pipeline keeps no in-memory class data
  across runs, so without this `merge_rbs_signatures` would run on
  an empty store. Also surfaces `rbs_signature_files`/`watch_files`
  for the live server's watcher.
- `store.rb` now propagates merged RBS signatures to aliases
  immediately during assignment by walking `method_attr.aliases`,
  and tracks assigned objects so a re-merge in the live-server
  reload path can clear stale signatures without nuking inline
  `#:` annotations.
- `rbs_helper.rb` keys singleton attributes as `Klass.attr` and
  instance attributes as `Klass#attr`, mirroring the method key
  format and preventing a singleton attr from clobbering an
  instance attr (or vice versa) when both share a name.

Drive-by cleanups while in the area: fold `.rbs` into
`remove_unparseable`'s extension regex; collapse the two identical
`rbs_*_key` helpers into one `rbs_key`; drop a redundant
`File.directory?` guard before `Dir[]`.

Author: st0012

lib/rdoc/rbs_helper.rb

@@ -58,7 +58,7 @@ def load_signatures(*dirs)
                 sigs = member.overloads.map { |o| o.method_type.to_s }
                 signatures[key] ||= sigs
               when RBS::AST::Members::AttrReader, RBS::AST::Members::AttrWriter, RBS::AST::Members::AttrAccessor
-                key = "#{class_name}##{member.name}"
+                key = member.kind == :singleton ? "#{class_name}.#{member.name}" : "#{class_name}##{member.name}"
                 signatures[key] ||= [member.type.to_s]
               end
             end

lib/rdoc/rdoc.rb

@@ -430,7 +430,7 @@ def parse_files(files)
 
   def remove_unparseable(files)
     files.reject do |file, *|
-      file =~ /\.(?:class|eps|erb|scpt\.txt|svg|ttf|yml)$/i or
+      file =~ /\.(?:class|eps|erb|rbs|scpt\.txt|svg|ttf|yml)$/i or
         (file =~ /tags$/i and
          /\A(\f\n[^,]+,\d+$|!_TAG_)/.match?(File.binread(file, 100)))
     end
@@ -470,6 +470,7 @@ def document(options)
       @store.load_cache
 
       parse_files @options.files
+      record_rbs_signature_mtimes
 
       @options.default_title = "RDoc Documentation"
 
@@ -488,7 +489,14 @@ def document(options)
 
     @store.load_cache
 
+    rbs_signatures_changed = rbs_signatures_changed?
+    # When only sig/*.rbs changed, no Ruby file would be reparsed and the
+    # cached HTML pipeline keeps no in-memory class data across runs, so
+    # force a full reparse to give merge_rbs_signatures a populated store.
+    @last_modified.clear if rbs_signatures_changed
+
     file_info = parse_files @options.files
+    record_rbs_signature_mtimes
 
     @options.default_title = "RDoc Documentation"
 
@@ -502,7 +510,7 @@ def document(options)
       puts
 
       puts @stats.report
-    elsif file_info.empty? then
+    elsif file_info.empty? && !rbs_signatures_changed then
       $stderr.puts "\nNo newer files." unless @options.quiet
     else
       gen_klass = @options.generator
@@ -553,11 +561,60 @@ def load_rbs_signatures
     sig_dir = File.join(@options.root.to_s, 'sig')
     sig_dirs << sig_dir if File.directory?(sig_dir)
     signatures = RDoc::RbsHelper.load_signatures(*sig_dirs)
-    @store.merge_rbs_signatures(signatures) unless signatures.empty?
+    @store.merge_rbs_signatures(signatures)
   rescue RBS::ParsingError, Errno::ENOENT, LoadError => e
     @options.warn "Failed to load RBS type signatures: #{e.message}"
   end
 
+  ##
+  # Returns all RBS signature files for the project.
+
+  def rbs_signature_files
+    Dir[File.join(@options.root.to_s, 'sig', '**', '*.rbs')].sort
+  end
+
+  ##
+  # Returns true if any RBS signature file has changed since the last run.
+
+  def rbs_signatures_changed?
+    current = rbs_signature_mtimes
+    previous = @last_modified.select { |file, _| File.extname(file) == '.rbs' }
+
+    return true unless (previous.keys - current.keys).empty?
+
+    current.any? do |file, mtime|
+      last_modified = @last_modified[file]
+      last_modified.nil? || mtime.to_i > last_modified.to_i
+    end
+  end
+
+  ##
+  # Records RBS signature file mtimes so normal generation freshness checks
+  # and the live server watcher can see signature-only edits.
+
+  def record_rbs_signature_mtimes
+    @last_modified.reject! { |file, _| File.extname(file) == '.rbs' }
+    @last_modified.merge! rbs_signature_mtimes
+  end
+
+  ##
+  # Files watched by the live preview server.
+
+  def watch_files
+    (@last_modified.keys + rbs_signature_files).uniq
+  end
+
+  def rbs_signature_file?(file) # :nodoc:
+    File.extname(file) == '.rbs'
+  end
+
+  def rbs_signature_mtimes # :nodoc:
+    rbs_signature_files.each_with_object({}) do |file, mtimes|
+      mtime = File.mtime(file) rescue nil
+      mtimes[file] = mtime if mtime
+    end
+  end
+
   ##
   # Starts a live-reloading HTTP server for previewing documentation.
   # Called from #document when <tt>--server</tt> is given.

lib/rdoc/server.rb

@@ -84,7 +84,7 @@ def start
     @tcp_server = TCPServer.new('127.0.0.1', @port)
     @running = true
 
-    @watcher_thread = start_watcher(@rdoc.last_modified.keys)
+    @watcher_thread = start_watcher(@rdoc.watch_files)
 
     url = "http://localhost:#{@port}"
     $stderr.puts "\nServing documentation at: \e]8;;#{url}\e\\#{url}\e]8;;\e\\"
@@ -294,9 +294,7 @@ def inject_live_reload(html, last_change_time)
   # re-parsing when changes are detected.
 
   def start_watcher(source_files)
-    @file_mtimes = source_files.each_with_object({}) do |f, h|
-      h[f] = File.mtime(f) rescue nil
-    end
+    @file_mtimes = file_mtimes_for(source_files)
 
     Thread.new do
       while @running
@@ -310,23 +308,41 @@ def start_watcher(source_files)
     end
   end
 
+  def file_mtimes_for(files)
+    files.each_with_object({}) do |f, h|
+      h[f] = File.mtime(f) rescue nil
+    end
+  end
+
   ##
   # Checks for modified, new, and deleted files.  Returns true if any
   # changes were found and processed.
 
   def check_for_changes
     changed = []
     removed = []
+    changed_rbs = []
+    removed_rbs = []
 
     @file_mtimes.each do |file, old_mtime|
       unless File.exist?(file)
-        removed << file
+        if @rdoc.rbs_signature_file?(file)
+          removed_rbs << file
+        else
+          removed << file
+        end
         next
       end
 
       current_mtime = File.mtime(file) rescue nil
       next unless current_mtime
-      changed << file if old_mtime.nil? || current_mtime > old_mtime
+      next unless old_mtime.nil? || current_mtime > old_mtime
+
+      if @rdoc.rbs_signature_file?(file)
+        changed_rbs << file
+      else
+        changed << file
+      end
     end
 
     file_list = @rdoc.normalized_file_list(
@@ -341,17 +357,26 @@ def check_for_changes
       end
     end
 
-    return false if changed.empty? && removed.empty?
+    @rdoc.rbs_signature_files.each do |file|
+      unless @file_mtimes.key?(file)
+        @file_mtimes[file] = nil
+        changed_rbs << file
+      end
+    end
+
+    return false if changed.empty? && removed.empty? && changed_rbs.empty? && removed_rbs.empty?
+
+    removed_rbs.each { |file| @file_mtimes.delete(file) }
 
-    reparse_and_refresh(changed, removed)
+    reparse_and_refresh(changed, removed, rbs_changed: !changed_rbs.empty? || !removed_rbs.empty?)
     true
   end
 
   ##
   # Re-parses changed files, removes deleted files from the store,
   # refreshes the generator, and invalidates caches.
 
-  def reparse_and_refresh(changed_files, removed_files)
+  def reparse_and_refresh(changed_files, removed_files, rbs_changed: false)
     @mutex.synchronize do
       unless removed_files.empty?
         $stderr.puts "Removed: #{removed_files.join(', ')}"
@@ -385,6 +410,17 @@ def reparse_and_refresh(changed_files, removed_files)
 
       @store.complete(@options.visibility)
 
+      if rbs_changed || !changed_files.empty?
+        duration_ms = measure do
+          @rdoc.load_rbs_signatures
+          @rdoc.record_rbs_signature_mtimes
+          @rdoc.rbs_signature_files.each do |file|
+            @file_mtimes[file] = File.mtime(file) rescue nil
+          end
+        end
+        $stderr.puts "Reloaded RBS signatures (#{duration_ms}ms)" if rbs_changed
+      end
+
       @generator.refresh_store_data
       @page_cache.clear
       @last_change_time = Time.now.to_f

lib/rdoc/store.rb

@@ -377,31 +377,59 @@ def type_name_lookup
   # Inline #: annotations take priority and are not overwritten.
 
   def merge_rbs_signatures(signatures)
+    clear_rbs_signatures
+
     all_classes_and_modules.each do |cm|
       cm.method_list.each do |method|
         next if method.type_signature_lines
 
-        key = method.singleton ? "#{cm.full_name}.#{method.name}" : "#{cm.full_name}##{method.name}"
-        sig = signatures[key]
+        sig = signatures[rbs_key(cm, method)]
 
         # RBS keys constructors as #initialize, but RDoc renames them to .new
         if !sig && method.name == 'new' && method.singleton
           sig = signatures["#{cm.full_name}#initialize"]
         end
 
-        method.type_signature_lines = sig if sig
+        assign_rbs_signature method, sig if sig
       end
 
       cm.attributes.each do |attr|
         next if attr.type_signature_lines
 
-        if (sig = signatures["#{cm.full_name}##{attr.name}"])
-          attr.type_signature_lines = sig
+        if (sig = signatures[rbs_key(cm, attr)])
+          assign_rbs_signature attr, sig
         end
       end
     end
   end
 
+  def assign_rbs_signature(method_attr, signature) # :nodoc:
+    @rbs_signature_method_attrs ||= []
+
+    method_attr.type_signature_lines = signature
+    @rbs_signature_method_attrs << method_attr
+
+    method_attr.aliases.each do |aliased|
+      next if aliased.type_signature_lines
+      aliased.type_signature_lines = signature
+      @rbs_signature_method_attrs << aliased
+    end
+  end
+
+  def clear_rbs_signatures # :nodoc:
+    return unless @rbs_signature_method_attrs
+
+    @rbs_signature_method_attrs.each do |method_attr|
+      method_attr.type_signature_lines = nil
+    end
+
+    @rbs_signature_method_attrs.clear
+  end
+
+  def rbs_key(cm, method_attr) # :nodoc:
+    method_attr.singleton ? "#{cm.full_name}.#{method_attr.name}" : "#{cm.full_name}##{method_attr.name}"
+  end
+
   ##
   # All TopLevels known to RDoc
 

test/rdoc/rbs_helper_test.rb

@@ -40,6 +40,21 @@ def greet: (String name) -> void
     end
   end
 
+  def test_load_signatures_keeps_instance_and_singleton_attributes_separate
+    Dir.mktmpdir do |dir|
+      File.write(File.join(dir, 'test.rbs'), <<~RBS)
+        class Greeter
+          attr_reader language: String
+          attr_reader self.language: Integer
+        end
+      RBS
+
+      sigs = RDoc::RbsHelper.load_signatures(dir)
+      assert_equal ['String'], sigs['Greeter#language']
+      assert_equal ['Integer'], sigs['Greeter.language']
+    end
+  end
+
   def test_signature_to_html_links_known_types
     lookup = { 'String' => 'String.html', 'Integer' => 'Integer.html' }
     result = RDoc::RbsHelper.signature_to_html(["(String) -> Integer"], lookup: lookup, from_path: 'Test.html')

test/rdoc/rdoc_rdoc_test.rb

@@ -2,6 +2,19 @@
 require_relative 'helper'
 
 class RDocRDocTest < RDoc::TestCase
+  class RegenerationTrackingGenerator
+    class << self
+      attr_accessor :generated_store
+    end
+
+    def initialize(store, _options)
+      @store = store
+    end
+
+    def generate
+      self.class.generated_store = @store
+    end
+  end
 
   def setup
     super
@@ -40,6 +53,63 @@ def test_document # functional test
     assert_equal 'title',          store.title
   end
 
+  def test_document_regenerates_when_rbs_file_changed
+    temp_dir do |dir|
+      source = File.join dir, 'example.rb'
+      sig_dir = File.join dir, 'sig'
+      sig = File.join sig_dir, 'example.rbs'
+      output_dir = File.join dir, 'doc'
+
+      FileUtils.mkdir_p sig_dir
+      FileUtils.mkdir_p output_dir
+
+      File.write source, <<~RUBY
+        class Example
+          def greet
+          end
+        end
+      RUBY
+
+      File.write sig, <<~RBS
+        class Example
+          def greet: () -> String
+        end
+      RBS
+
+      source_mtime = Time.at 1000
+      old_sig_mtime = Time.at 1000
+      new_sig_mtime = Time.at 2000
+      FileUtils.touch source, mtime: source_mtime
+      FileUtils.touch sig, mtime: new_sig_mtime
+
+      File.open @rdoc.output_flag_file(output_dir), 'w' do |io|
+        io.puts Time.at(1500).rfc2822
+        io.puts "#{source}\t#{source_mtime.rfc2822}"
+        io.puts "#{sig}\t#{old_sig_mtime.rfc2822}"
+      end
+
+      options = RDoc::Options.new
+      options.files = [source]
+      options.root = Pathname dir
+      options.op_dir = output_dir
+      options.force_update = false
+      options.quiet = true
+      options.generator = RegenerationTrackingGenerator
+      RegenerationTrackingGenerator.generated_store = nil
+
+      capture_output do
+        RDoc::RDoc.new.document options
+      end
+
+      store = RegenerationTrackingGenerator.generated_store
+      refute_nil store
+
+      example = store.find_class_or_module 'Example'
+      greet = example.find_method 'greet', false
+      assert_equal ['() -> String'], greet.type_signature_lines
+    end
+  end
+
   def test_document_with_dry_run # functional test
     options = RDoc::Options.new
     options.files = [File.expand_path('../xref_data.rb', __FILE__)]