rdoc 6.3.4.1 → 8.0.0

data/lib/rdoc/store.rb

@@ -54,7 +54,7 @@ class RDoc::Store
     # Creates a new MissingFileError for the missing +file+ for the given
     # +name+ that should have been in the +store+.
 
-    def initialize store, file, name
+    def initialize(store, file, name)
       @store = store
       @file  = file
       @name  = name
@@ -94,11 +94,7 @@ class RDoc::Store
 
   attr_accessor :path
 
-  ##
-  # The RDoc::RDoc driver for this parse tree.  This allows classes consulting
-  # the documentation tree to access user-set options, for example.
-
-  attr_accessor :rdoc
+  attr_reader :options
 
   ##
   # Type of ri datastore this was loaded from.  See RDoc::RI::Driver,
@@ -124,11 +120,11 @@ class RDoc::Store
   ##
   # Creates a new Store of +type+ that will load or save to +path+
 
-  def initialize path = nil, type = nil
-    @dry_run  = false
-    @encoding = nil
-    @path     = path
-    @rdoc     = nil
+  def initialize(options, path: nil, type: nil)
+    @options  = options
+    @dry_run  = options.dry_run
+    @encoding = options.encoding
+    @path     = path || options.op_dir
     @type     = type
 
     @cache = {
@@ -139,10 +135,10 @@ class RDoc::Store
       :c_singleton_class_variables => {},
       :encoding                    => @encoding,
       :instance_methods            => {},
-      :main                        => nil,
+      :main                        => options.main_page,
       :modules                     => [],
       :pages                       => [],
-      :title                       => nil,
+      :title                       => options.title,
     }
 
     @classes_hash = {}
@@ -166,14 +162,14 @@ class RDoc::Store
   # Adds +module+ as an enclosure (namespace) for the given +variable+ for C
   # files.
 
-  def add_c_enclosure variable, namespace
+  def add_c_enclosure(variable, namespace)
     @c_enclosure_classes[variable] = namespace
   end
 
   ##
   # Adds C variables from an RDoc::Parser::C
 
-  def add_c_variables c_parser
+  def add_c_variables(c_parser)
     filename = c_parser.top_level.relative_name
 
     @c_class_variables[filename] = make_variable_map c_parser.classes
@@ -185,7 +181,7 @@ class RDoc::Store
   # Adds the file with +name+ as an RDoc::TopLevel to the store.  Returns the
   # created RDoc::TopLevel.
 
-  def add_file absolute_name, relative_name: absolute_name, parser: nil
+  def add_file(absolute_name, relative_name: absolute_name, parser: nil)
     unless top_level = @files_hash[relative_name] then
       top_level = RDoc::TopLevel.new absolute_name, relative_name
       top_level.parser = parser if parser
@@ -197,9 +193,139 @@ class RDoc::Store
     top_level
   end
 
-  def update_parser_of_file(absolute_name, parser)
-    if top_level = @files_hash[absolute_name] then
-      @text_files_hash[absolute_name] = top_level if top_level.text?
+  ##
+  # Removes a file and its classes/modules from the store.  Used by the
+  # live-reloading server when a source file is deleted.
+  #
+  # Note: this does not handle reopened classes correctly.  If a class is
+  # defined across multiple files (e.g. +Foo+ in both +a.rb+ and +b.rb+),
+  # deleting one file removes the entire class from the store — including
+  # the parts contributed by the other file.  Saving the remaining file
+  # triggers a re-parse that restores it.
+
+  def remove_file(relative_name)
+    top_level = @files_hash.delete(relative_name)
+    @text_files_hash.delete(relative_name)
+    @c_class_variables.delete(relative_name)
+    @c_singleton_class_variables.delete(relative_name)
+    return unless top_level
+
+    remove_classes_and_modules(top_level.classes_or_modules)
+  end
+
+  ##
+  # Removes a file's contributions (methods, constants, comments, etc.)
+  # from its classes and modules.  If no other files contribute to a
+  # class or module, it is removed from the store entirely.  This
+  # prevents duplication when the file is re-parsed while preserving
+  # shared namespaces like +RDoc+ that span many files.
+
+  def clear_file_contributions(relative_name, keep_position: false)
+    top_level = @files_hash[relative_name]
+    return unless top_level
+
+    top_level.classes_or_modules.each do |cm|
+      # Remove methods and attributes contributed by this file
+      cm.method_list.reject! { |m| m.file == top_level }
+      cm.attributes.reject! { |a| a.file == top_level }
+
+      # Rebuild methods_hash from remaining methods and attributes
+      cm.methods_hash.clear
+      cm.method_list.each { |m| cm.methods_hash[m.pretty_name] = m }
+      cm.attributes.each { |a| cm.methods_hash[a.pretty_name] = a }
+
+      # Remove constants contributed by this file
+      cm.constants.reject! { |c| c.file == top_level }
+      cm.constants_hash.clear
+      cm.constants.each { |c| cm.constants_hash[c.name] = c }
+
+      # Remove includes, extends, and aliases from this file
+      cm.includes.reject! { |i| i.file == top_level }
+      cm.extends.reject! { |e| e.file == top_level }
+      cm.aliases.reject! { |a| a.file == top_level }
+      cm.external_aliases.reject! { |a| a.file == top_level }
+
+      # Clear or remove comment entries from this file
+      if cm.is_a?(RDoc::ClassModule)
+        if keep_position
+          cm.comment_location[top_level] = [] if cm.comment_location.key?(top_level)
+        else
+          cm.comment_location.delete(top_level)
+        end
+        cm.rebuild_comment_from_location
+      end
+
+      unless keep_position
+        # Remove this file from the class/module's file list
+        cm.in_files.delete(top_level)
+
+        # If no files contribute to this class/module anymore, remove it
+        # from the store entirely.  This handles file deletion correctly
+        # for classes that are only defined in the deleted file, while
+        # preserving classes that span multiple files.
+        if cm.in_files.empty?
+          if cm.is_a?(RDoc::NormalModule)
+            @modules_hash.delete(cm.full_name)
+          else
+            @classes_hash.delete(cm.full_name)
+          end
+          cm.parent&.classes_hash&.delete(cm.name)
+          cm.parent&.modules_hash&.delete(cm.name)
+        end
+      end
+    end
+
+    # Clear the TopLevel's class/module list to prevent duplicates
+    top_level.classes_or_modules.clear
+  end
+
+  ##
+  # Removes stale empty placeholders left by +clear_file_contributions+ with
+  # <tt>keep_position: true</tt>.  After re-parsing, a file may no longer
+  # define a class it previously contributed to, leaving an empty entry in
+  # +comment_location+ and a stale +in_files+ reference.  Call this after
+  # all re-parsing is complete.
+
+  def cleanup_stale_contributions
+    all_classes_and_modules.each do |cm|
+      cm.comment_location.delete_if { |_, comments| comments.empty? }
+      cm.rebuild_comment_from_location
+
+      cm.in_files.select! { |tl| cm.comment_location.key?(tl) ||
+        cm.method_list.any? { |m| m.file == tl } ||
+        cm.attributes.any? { |a| a.file == tl } ||
+        cm.constants.any? { |c| c.file == tl } }
+
+      if cm.in_files.empty?
+        if cm.is_a?(RDoc::NormalModule)
+          @modules_hash.delete(cm.full_name)
+        else
+          @classes_hash.delete(cm.full_name)
+        end
+        cm.parent&.classes_hash&.delete(cm.name)
+        cm.parent&.modules_hash&.delete(cm.name)
+      end
+    end
+  end
+
+  ##
+  # Make sure any references to C variable names are resolved to the corresponding class.
+  #
+
+  def resolve_c_superclasses
+    @classes_hash.each_value do |klass|
+      if klass.superclass.is_a?(String) && (candidate = find_c_enclosure(klass.superclass))
+        klass.superclass = candidate
+      end
+    end
+  end
+
+  ##
+  # Caches +relative_name+ in the text files hash, if it is a text file.
+
+  def cache_text_file(relative_name)
+    if top_level = @files_hash[relative_name]
+      @text_files_hash[relative_name] = top_level if top_level.text?
     end
   end
 
@@ -217,6 +343,86 @@ class RDoc::Store
     @classes_hash.values + @modules_hash.values
   end
 
+  ##
+  # Returns a hash mapping class/module names to their paths, for use
+  # by type signature linking. Maps both qualified names (Foo::Bar) and
+  # unambiguous unqualified names (Bar). Ambiguous unqualified names
+  # (where multiple classes share the same name) are excluded to avoid
+  # wrong links. Cached after first call.
+
+  ##
+  # Invalidates the cached type name lookup.  Server mode calls this after
+  # re-parsing changes the set of classes and modules.
+
+  def invalidate_type_name_lookup # :nodoc:
+    @type_name_lookup = nil
+  end
+
+  def type_name_lookup
+    @type_name_lookup ||= begin
+      lookup = {}
+      unqualified_names = {}
+      ambiguous_names = {}
+      all_classes_and_modules.each do |cm|
+        lookup[cm.full_name] = cm.path
+        unqualified_name = cm.name
+
+        if ambiguous_names[unqualified_name]
+          # already known ambiguous, skip
+        elsif unqualified_names.key?(unqualified_name)
+          unqualified_names.delete(unqualified_name)
+          ambiguous_names[unqualified_name] = true
+        else
+          unqualified_names[unqualified_name] = cm.path
+        end
+      end
+      lookup.merge!(unqualified_names)
+    end
+  end
+
+  ##
+  # Stores RBS type signatures loaded from sidecar .rbs files, keyed by
+  # "ClassName#method" or "ClassName.method".  Replaces any previously
+  # stored set, so passing +{}+ clears it.  Inline +#:+ annotations on
+  # method objects are NOT touched — those are owned by the source file.
+
+  def merge_rbs_signatures(signatures)
+    @rbs_signatures = signatures
+  end
+
+  ##
+  # Returns the RBS type signature lines for +method_attr+ from loaded
+  # sidecar +.rbs+ files, or +nil+ if none.  Falls through to the
+  # canonical method for aliases, and handles +initialize+ -> +.new+
+  # singleton mapping.
+
+  def rbs_signature_for(method_attr)
+    return nil unless @rbs_signatures
+    cm = method_attr.parent
+    return nil unless cm.respond_to?(:full_name)
+
+    key = method_attr.singleton ? "#{cm.full_name}.#{method_attr.name}" : "#{cm.full_name}##{method_attr.name}"
+    sig = @rbs_signatures[key]
+
+    # RBS keys constructors as #initialize, but RDoc renames them to .new
+    if !sig && method_attr.name == 'new' && method_attr.singleton
+      sig = @rbs_signatures["#{cm.full_name}#initialize"]
+    end
+
+    # For aliases, fall through to the canonical method (its inline #:
+    # takes precedence over any sidecar signature on the alias's name).
+    if !sig && method_attr.is_alias_for
+      canonical = method_attr.is_alias_for
+      sig = canonical.type_signature_lines || rbs_signature_for(canonical)
+    end
+
+    sig
+  end
+
+  def clear_rbs_signatures # :nodoc:
+    @rbs_signatures = nil
+  end
+
   ##
   # All TopLevels known to RDoc
 
@@ -257,7 +463,7 @@ class RDoc::Store
   ##
   # Path to the ri data for +klass_name+
 
-  def class_file klass_name
+  def class_file(klass_name)
     name = klass_name.split('::').last
     File.join class_path(klass_name), "cdesc-#{name}.ri"
   end
@@ -273,7 +479,7 @@ class RDoc::Store
   ##
   # Path where data for +klass_name+ will be stored (methods or class data)
 
-  def class_path klass_name
+  def class_path(klass_name)
     File.join @path, *klass_name.split('::')
   end
 
@@ -288,7 +494,7 @@ class RDoc::Store
   # Removes empty items and ensures item in each collection are unique and
   # sorted
 
-  def clean_cache_collection collection # :nodoc:
+  def clean_cache_collection(collection) # :nodoc:
     collection.each do |name, item|
       if item.empty? then
         collection.delete name
@@ -316,7 +522,7 @@ class RDoc::Store
   #
   # See also RDoc::Context#remove_from_documentation?
 
-  def complete min_visibility
+  def complete(min_visibility)
     fix_basic_object_inheritance
 
     # cache included modules before they are removed from the documentation
@@ -363,7 +569,7 @@ class RDoc::Store
   ##
   # Finds the enclosure (namespace) for the given C +variable+.
 
-  def find_c_enclosure variable
+  def find_c_enclosure(variable)
     @c_enclosure_classes.fetch variable do
       break unless name = @c_enclosure_names[variable]
 
@@ -388,14 +594,14 @@ class RDoc::Store
   ##
   # Finds the class with +name+ in all discovered classes
 
-  def find_class_named name
+  def find_class_named(name)
     @classes_hash[name]
   end
 
   ##
   # Finds the class with +name+ starting in namespace +from+
 
-  def find_class_named_from name, from
+  def find_class_named_from(name, from)
     from = find_class_named from unless RDoc::Context === from
 
     until RDoc::TopLevel === from do
@@ -413,7 +619,7 @@ class RDoc::Store
   ##
   # Finds the class or module with +name+
 
-  def find_class_or_module name
+  def find_class_or_module(name)
     name = $' if name =~ /^::/
     @classes_hash[name] || @modules_hash[name]
   end
@@ -421,14 +627,14 @@ class RDoc::Store
   ##
   # Finds the file with +name+ in all discovered files
 
-  def find_file_named name
+  def find_file_named(name)
     @files_hash[name]
   end
 
   ##
   # Finds the module with +name+ in all discovered modules
 
-  def find_module_named name
+  def find_module_named(name)
     @modules_hash[name]
   end
 
@@ -436,7 +642,7 @@ class RDoc::Store
   # Returns the RDoc::TopLevel that is a text file and has the given
   # +file_name+
 
-  def find_text_page file_name
+  def find_text_page(file_name)
     @text_files_hash.each_value.find do |file|
       file.full_name == file_name
     end
@@ -449,7 +655,7 @@ class RDoc::Store
   #--
   # TODO  aliases should be registered by Context#add_module_alias
 
-  def find_unique all_hash
+  def find_unique(all_hash)
     unique = []
 
     all_hash.each_pair do |full_name, cm|
@@ -592,7 +798,7 @@ class RDoc::Store
   ##
   # Loads ri data for +klass_name+ and hooks it up to this store.
 
-  def load_class klass_name
+  def load_class(klass_name)
     obj = load_class_data klass_name
 
     obj.store = self
@@ -610,7 +816,7 @@ class RDoc::Store
   ##
   # Loads ri data for +klass_name+
 
-  def load_class_data klass_name
+  def load_class_data(klass_name)
     file = class_file klass_name
 
     marshal_load(file)
@@ -623,7 +829,7 @@ class RDoc::Store
   ##
   # Loads ri data for +method_name+ in +klass_name+
 
-  def load_method klass_name, method_name
+  def load_method(klass_name, method_name)
     file = method_file klass_name, method_name
 
     obj = marshal_load(file)
@@ -639,7 +845,7 @@ class RDoc::Store
   ##
   # Loads ri data for +page_name+
 
-  def load_page page_name
+  def load_page(page_name)
     file = page_file page_name
 
     obj = marshal_load(file)
@@ -662,7 +868,7 @@ class RDoc::Store
   ##
   # Sets the main page for this RDoc store.
 
-  def main= page
+  def main=(page)
     @cache[:main] = page
   end
 
@@ -670,7 +876,7 @@ class RDoc::Store
   # Converts the variable => ClassModule map +variables+ from a C parser into
   # a variable => class name map.
 
-  def make_variable_map variables
+  def make_variable_map(variables)
     map = {}
 
     variables.each { |variable, class_module|
@@ -683,7 +889,7 @@ class RDoc::Store
   ##
   # Path to the ri data for +method_name+ in +klass_name+
 
-  def method_file klass_name, method_name
+  def method_file(klass_name, method_name)
     method_name = method_name.split('::').last
     method_name =~ /#(.*)/
     method_type = $1 ? 'i' : 'c'
@@ -709,10 +915,10 @@ class RDoc::Store
   end
 
   ##
-  # Returns the RDoc::TopLevel that is a text file and has the given +name+
+  # Returns the RDoc::TopLevel that is a file and has the given +name+
 
-  def page name
-    @text_files_hash.each_value.find do |file|
+  def page(name)
+    @files_hash.each_value.find do |file|
       file.page_name == name or file.base_name == name
     end
   end
@@ -720,7 +926,7 @@ class RDoc::Store
   ##
   # Path to the ri data for +page_name+
 
-  def page_file page_name
+  def page_file(page_name)
     file_name = File.basename(page_name).gsub('.', '_')
 
     File.join @path, File.dirname(page_name), "page-#{file_name}.ri"
@@ -731,7 +937,7 @@ class RDoc::Store
   #
   # See RDoc::Context#remove_from_documentation?
 
-  def remove_nodoc all_hash
+  def remove_nodoc(all_hash)
     all_hash.keys.each do |name|
       context = all_hash[name]
       all_hash.delete(name) if context.remove_from_documentation?
@@ -751,7 +957,7 @@ class RDoc::Store
         save_method klass, method
       end
 
-      klass.each_attribute do |attribute|
+      klass.attributes.each do |attribute|
         save_method klass, attribute
       end
     end
@@ -793,7 +999,7 @@ class RDoc::Store
   ##
   # Writes the ri data for +klass+ (or module)
 
-  def save_class klass
+  def save_class(klass)
     full_name = klass.full_name
 
     FileUtils.mkdir_p class_path(full_name) unless @dry_run
@@ -867,7 +1073,7 @@ class RDoc::Store
   ##
   # Writes the ri data for +method+ on +klass+
 
-  def save_method klass, method
+  def save_method(klass, method)
     full_name = klass.full_name
 
     FileUtils.mkdir_p class_path(full_name) unless @dry_run
@@ -890,7 +1096,7 @@ class RDoc::Store
   ##
   # Writes the ri data for +page+
 
-  def save_page page
+  def save_page(page)
     return unless page.text?
 
     path = page_file page.full_name
@@ -937,7 +1143,7 @@ class RDoc::Store
   ##
   # Sets the title page for this RDoc store.
 
-  def title= title
+  def title=(title)
     @cache[:title] = title
   end
 
@@ -967,6 +1173,19 @@ class RDoc::Store
   end
 
   private
+
+  def remove_classes_and_modules(cms)
+    cms.each do |cm|
+      remove_classes_and_modules(cm.classes_and_modules)
+
+      if cm.is_a?(RDoc::NormalModule)
+        @modules_hash.delete(cm.full_name)
+      else
+        @classes_hash.delete(cm.full_name)
+      end
+    end
+  end
+
   def marshal_load(file)
     File.open(file, 'rb') {|io| Marshal.load(io, MarshalFilter)}
   end