rbs 2.6.0 → 2.7.0.pre.1

data/lib/rdoc_plugin/parser.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require 'rbs'
+
+module RBS
+  module RDocPlugin
+    class Parser
+
+      attr_accessor :top_level, :content
+
+      def initialize(top_level, content)
+        @top_level = top_level
+        @content = content
+      end
+
+      def scan
+        ast = ::RBS::Parser.parse_signature(@content)
+        ast.each do |decl|
+          parse_member(decl: decl, context: @top_level)
+        end
+        @top_level
+      end
+
+      def parse_member(decl:, context:, outer_name: nil)
+        case decl
+        when ::RBS::AST::Declarations::Class
+          parse_class_decl(decl: decl, context: context, outer_name: outer_name)
+        when ::RBS::AST::Declarations::Module
+          parse_module_decl(decl: decl, context: context, outer_name: outer_name)
+        when ::RBS::AST::Declarations::Constant
+          context = @top_level.find_class_or_module outer_name.to_s if outer_name
+          parse_constant_decl(decl: decl, context: context, outer_name: outer_name)
+        when ::RBS::AST::Declarations::Interface
+          parse_module_decl(decl: decl, context: context, outer_name: outer_name)
+        when ::RBS::AST::Members::MethodDefinition
+          context = @top_level.find_class_or_module outer_name.to_s if outer_name
+          parse_method_decl(decl: decl, context: context, outer_name: outer_name)
+        when ::RBS::AST::Members::Alias
+          context = @top_level.find_class_or_module outer_name.to_s if outer_name
+          parse_method_alias_decl(decl: decl, context: context, outer_name: outer_name)
+        when ::RBS::AST::Members::AttrReader, ::RBS::AST::Members::AttrWriter, ::RBS::AST::Members::AttrAccessor
+          context = @top_level.find_class_or_module outer_name.to_s if outer_name
+          parse_attr_decl(decl: decl, context: context, outer_name: outer_name)
+        when ::RBS::AST::Members::Include
+          context = @top_level.find_class_or_module outer_name.to_s if outer_name
+          parse_include_decl(decl: decl, context: context, outer_name: outer_name)
+        when ::RBS::AST::Members::Extend
+          context = @top_level.find_class_or_module outer_name.to_s if outer_name
+          parse_extend_decl(decl: decl, context: context, outer_name: outer_name)
+        end
+      end
+
+      def parse_class_decl(decl:, context:, outer_name: nil)
+        full_name = fully_qualified_name(outer_name: outer_name, decl: decl)
+        klass = context.add_class(RDoc::NormalClass, full_name.to_s, decl.super_class&.name&.to_s || "::Object")
+        klass.add_comment(construct_comment(context: context, comment: comment_string(decl)), context) if decl.comment
+        decl.members.each { |member| parse_member(decl: member, context: context, outer_name: full_name) }
+      end
+
+      def parse_module_decl(decl:, context:, outer_name: nil)
+        full_name = fully_qualified_name(outer_name: outer_name, decl: _ = decl)
+        kmodule = context.add_module(RDoc::NormalModule, full_name.to_s)
+        kmodule.add_comment(construct_comment(context: context, comment: comment_string(decl)), context) if decl.comment
+        decl.members.each { |member| parse_member(decl: member, context: context, outer_name: full_name) }
+      end
+
+      def parse_constant_decl(decl:, context:, outer_name: nil)
+        comment = decl.comment ? construct_comment(context: context, comment: comment_string(decl)) : nil
+        constant = RDoc::Constant.new(decl.name.to_s, decl.type.to_s, comment)
+        context.add_constant(constant)
+      end
+
+      def parse_method_decl(decl:, context:, outer_name: nil)
+        method = RDoc::AnyMethod.new(nil, decl.name.to_s)
+        method.singleton = decl.singleton?
+        method.visibility = decl.visibility
+        method.call_seq = decl.types.map { |type| "#{decl.name.to_s}#{type.to_s}" }.join("\n")
+        if loc = decl.location
+          method.start_collecting_tokens
+          method.add_token({ line_no: 1, char_no: 1, kind: :on_comment, text: "# File #{@top_level.relative_name}, line(s) #{loc.start_line}:#{loc.end_line}\n" })
+          method.add_token({ line_no: 1, char_no: 1, text: loc.source })
+          method.line = loc.start_line
+        end
+        method.comment = construct_comment(context: context, comment: comment_string(decl)) if decl.comment
+        context.add_method(method)
+      end
+
+      def parse_method_alias_decl(decl:, context:, outer_name: nil)
+        alias_def = RDoc::Alias.new(nil, decl.old_name.to_s, decl.new_name.to_s, nil, decl.kind == :singleton)
+        alias_def.comment = construct_comment(context: context, comment: comment_string(decl)) if decl.comment
+        context.add_alias(alias_def)
+      end
+
+      def parse_attr_decl(decl:, context:, outer_name: nil)
+        rw = case decl
+             when ::RBS::AST::Members::AttrReader
+               'R'
+             when ::RBS::AST::Members::AttrWriter
+               'W'
+             when ::RBS::AST::Members::AttrAccessor
+               'RW'
+             end
+        attribute = RDoc::Attr.new(nil, decl.name.to_s, rw, nil, decl.kind == :singleton)
+        attribute.visibility = decl.visibility
+        attribute.comment = construct_comment(context: context, comment: comment_string(decl)) if decl.comment
+        context.add_attribute(attribute)
+      end
+
+      def parse_include_decl(decl:, context:, outer_name: nil)
+        name = decl.name.to_s
+        outer_names = outer_name ? outer_name.to_s.split("::") : []
+        qualified_name = ''
+        outer_names.each do |namespace|
+          qualified_name += namespace
+          if (module_name = @top_level.find_module_named((qualified_name += "::") + name))
+            name = module_name.full_name
+            break
+          end
+        end
+        include_decl = RDoc::Include.new(name, nil)
+        include_decl.comment = construct_comment(context: context, comment: comment_string(decl)) if decl.comment
+        context.add_include(include_decl)
+      end
+
+      def parse_extend_decl(decl:, context:, outer_name: nil)
+        name = decl.name.to_s
+        outer_names = outer_name ? outer_name.to_s.split("::") : []
+        qualified_name = ''
+        outer_names.each do |namespace|
+          qualified_name += namespace
+          if (module_name = @top_level.find_module_named((qualified_name += "::") + name))
+            name = module_name.full_name
+            break
+          end
+        end
+        extend_decl = RDoc::Extend.new(name, nil)
+        extend_decl.comment = construct_comment(context: context, comment: comment_string(decl)) if decl.comment
+        context.add_extend(extend_decl)
+      end
+
+      private
+
+      def construct_comment(context:, comment:)
+        comment = RDoc::Comment.new(comment, context)
+        comment.format = "markdown"
+        comment
+      end
+
+      def comment_string(with_comment)
+        comment = with_comment.comment or raise "Object with `#comment` returning a object is expected"
+        comment.string
+      end
+
+      def fully_qualified_name(outer_name:, decl:)
+        if outer_name
+          (outer_name + decl.name)
+        else
+          decl.name
+        end
+      end
+    end
+  end
+end

data/schema/methodType.json

@@ -9,9 +9,15 @@
         },
         "required": {
           "type": "boolean"
+        },
+        "self_type": {
+          "oneOf": [
+            { "$ref": "#" },
+            { "type": "null" }
+          ]
         }
       },
-      "required": ["type", "required"]
+      "required": ["type", "required", "self_type"]
     }
   },
   "title": "Method type: `() -> void`, `[X] (::Integer) { (::String) -> X } -> Array[X]`, ...",

data/schema/types.json

@@ -238,9 +238,21 @@
         },
         "location": {
           "$ref": "location.json"
+        },
+        "block": {
+          "oneOf": [
+            { "$ref": "methodType.json#/definitions/block" },
+            { "type": "null" }
+          ]
+        },
+        "self_type": {
+          "oneOf": [
+            { "$ref": "#" },
+            { "type": "null" }
+          ]
         }
       },
-      "required": ["class", "type", "location"]
+      "required": ["class", "type", "location", "block", "self_type"]
     },
     "literal": {
       "title": "Literal types: `1`, `:foo`, `\"foo\"`, ...",

data/sig/ancestor_builder.rbs

@@ -1,15 +1,68 @@
 module RBS
   class DefinitionBuilder
+    # AncestorBuilder calculates the ancestors of a class or module.
+    #
     class AncestorBuilder
+      # OneAncestors represents a list of _direct_ ancestors of a type name
+      #
+      # _Direct_ ancestors is defined as follows:
+      #
+      # * Super class is a direct ancestor
+      # * Self type constraints are direct ancestors
+      # * Mixin modules are direct ancestors
+      # * Mixin interfaces are direct ancestors
+      #
+      # The optional attributes are defined by the type of the ancestors object, one of the following five groups:
+      #
+      # 1. Instance of a class -- with super_class, included_modules, included_interfaces, and prepended_modules
+      # 2. Instance of a module -- with self_types, included_modules, included_interfaces, and prepended_modules
+      # 3. Singleton of a class or module -- with super_class, extended_modules, and extended_interfaces
+      # 4. Interface -- with included_interfaces
+      #
       class OneAncestors
         attr_reader type_name: TypeName
         attr_reader params: Array[Symbol]?
+
+        # Returns super_class ancestor if specified
+        #
+        # * Always `nil` if this is not a class.
+        #
         attr_reader super_class: Definition::Ancestor::t?
+
+        # Returns list of _self type constraints_ of a module
+        #
+        # * Returns `nil` if it is not a module instance.
+        #
         attr_reader self_types: Array[Definition::Ancestor::Instance]?
+
+        # Returns the list of included modules
+        #
+        # * Returns `nil` if it is an interface or it is a singleton.
+        #
         attr_reader included_modules: Array[Definition::Ancestor::Instance]?
+
+        # Returns the list of included interfaces
+        #
+        # * Returns `nil` it it is a singleton.
+        #
         attr_reader included_interfaces: Array[Definition::Ancestor::Instance]?
+
+        # Returns the list of prepended modules
+        #
+        # * Returns `nil` if it is an interface or it is a singleton.
+        #
         attr_reader prepended_modules: Array[Definition::Ancestor::Instance]?
+
+        # Returns the list of extended modules
+        #
+        # * Returns `nil` if it is an interface or it is an instance.
+        #
         attr_reader extended_modules: Array[Definition::Ancestor::Instance]?
+
+        # Returns the list of extended interfaces
+        #
+        # * Returns `nil` if it is an interface or it is an instance.
+        #
         attr_reader extended_interfaces: Array[Definition::Ancestor::Instance]?
 
         def initialize: (type_name: TypeName,
@@ -25,12 +78,16 @@ module RBS
         def each_ancestor: { (Definition::Ancestor::t) -> void } -> void
                          | -> Enumerator[Definition::Ancestor::t, void]
 
+        # Returns a OneAncestors object for class instance
         def self.class_instance: (type_name: TypeName, params: Array[Symbol], super_class: Definition::Ancestor::t?) -> instance
 
-        def self.singleton: (type_name: TypeName, super_class: Definition::Ancestor::t?) -> instance
-
+        # Returns a OneAncestors object for module instance
         def self.module_instance: (type_name: TypeName, params: Array[Symbol]) -> instance
 
+        # Returns a OneAncestors object for class/module singleton
+        def self.singleton: (type_name: TypeName, super_class: Definition::Ancestor::t) -> instance
+
+        # Returns a OneAncestors object for interface
         def self.interface: (type_name: TypeName, params: Array[Symbol]) -> instance
 
         def each_included_module: () { (Definition::Ancestor::Instance) -> void } -> void
@@ -65,7 +122,11 @@ module RBS
 
       def initialize: (env: Environment) -> void
 
-      def validate_super_class!: (TypeName, Environment::ClassEntry) -> void
+      def instance_ancestors: (TypeName, ?building_ancestors: Array[Definition::Ancestor::t]) -> Definition::InstanceAncestors
+
+      def singleton_ancestors: (TypeName, ?building_ancestors: Array[Definition::Ancestor::t]) -> Definition::SingletonAncestors
+
+      def interface_ancestors: (TypeName, ?building_ancestors: Array[Definition::Ancestor::t]) -> Definition::InstanceAncestors
 
       def one_instance_ancestors: (TypeName) -> OneAncestors
 
@@ -73,11 +134,9 @@ module RBS
 
       def one_interface_ancestors: (TypeName) -> OneAncestors
 
-      def instance_ancestors: (TypeName, ?building_ancestors: Array[Definition::Ancestor::t]) -> Definition::InstanceAncestors
-
-      def singleton_ancestors: (TypeName, ?building_ancestors: Array[Definition::Ancestor::t]) -> Definition::SingletonAncestors
+      private
 
-      def interface_ancestors: (TypeName, ?building_ancestors: Array[Definition::Ancestor::t]) -> Definition::InstanceAncestors
+      def validate_super_class!: (TypeName, Environment::ClassEntry) -> void
 
       def mixin_ancestors: (Environment::ClassEntry | Environment::ModuleEntry,
                             TypeName,

data/sig/annotation.rbs

@@ -2,12 +2,13 @@ module RBS
   module AST
     # RBS allows writing annotations of declarations and members.
     #
-    #    %a{annotation_here}
-    #    class Hello
-    #      %a{rbs:test:skip}
-    #      def foo: () -> void
-    #    end
-    #
+    # ```rbs
+    # %a{annotation_here}
+    # class Hello
+    #   %a{rbs:test:skip}
+    #   def foo: () -> void
+    # end
+    # ```
     class Annotation
       attr_reader string: String
       attr_reader location: Location[untyped, untyped]?

data/sig/builtin_names.rbs

@@ -3,6 +3,8 @@ module RBS
     class Name
       attr_reader name: TypeName
 
+      @singleton_type: Types::t?
+
       def initialize: (name: TypeName) -> void
 
       def to_s: () -> String

data/sig/cli.rbs

@@ -26,6 +26,14 @@ module RBS
     attr_reader stdout: _IO
     attr_reader stderr: _IO
 
+    # The copy of `args` passed to `run`.
+    #
+    # `OptionParser#order!` mutates given `arg`, the `run_***` actions should read `original_args` to get the original commandline arguments.
+    #
+    # Returns `nil` if called before `#run` call.
+    #
+    attr_reader original_args: Array[String]
+
     def initialize: (stdout: IO, stderr: IO) -> void
 
     COMMANDS: Array[Symbol]

data/sig/collection/config.rbs

@@ -3,6 +3,7 @@ module RBS
     # This class represent the configration file.
     class Config
       class CollectionNotAvailable < StandardError
+        def initialize: () -> void
       end
 
       class LockfileGenerator
@@ -11,6 +12,10 @@ module RBS
         attr_reader lock_path: Pathname
         attr_reader gemfile_lock: Bundler::LockfileParser
 
+        type gem_queue_entry = { name: String, version: String? }
+
+        @gem_queue: Array[gem_queue_entry]
+
         def self.generate: (config_path: Pathname, gemfile_lock_path: Pathname, ?with_lockfile: boolish) -> Config
 
         def initialize: (config_path: Pathname, gemfile_lock_path: Pathname, with_lockfile: boolish) -> void
@@ -27,7 +32,7 @@ module RBS
 
         def remove_ignored_gems!: () -> void
 
-        def find_source: (name: String) -> untyped
+        def find_source: (name: String) -> Sources::_Source?
 
         def find_best_version: (version: String?, versions: Array[String]) -> Gem::Version
       end
@@ -43,6 +48,10 @@ module RBS
 
       @config_path: Pathname
 
+      @data: untyped
+
+      @sources: Array[Sources::_Source]
+
       def self.generate_lockfile: (config_path: Pathname, gemfile_lock_path: Pathname, ?with_lockfile: boolish) -> Config
 
       def self.from_path: (Pathname path) -> Config
@@ -54,9 +63,9 @@ module RBS
       # config_path is necessary to resolve relative repo_path
       def initialize: (untyped data, config_path: Pathname) -> void
 
-      def add_gem: (untyped gem) -> untyped
+      def add_gem: (gem_entry gem) -> void
 
-      def gem: (String gem_name) -> untyped
+      def gem: (String gem_name) -> gem_entry?
 
       def repo_path: () -> Pathname
 
@@ -64,7 +73,7 @@ module RBS
 
       def dump_to: (Pathname) -> void
 
-      def gems: () -> Array[untyped]
+      def gems: () -> Array[gem_entry]
 
       def check_rbs_availability!: () -> void
     end

data/sig/collection/installer.rbs

@@ -9,6 +9,8 @@ module RBS
 
       private
 
+      @source_for: Hash[Sources::source_entry, Sources::_Source]
+
       def source_for: (Config::gem_entry) -> Sources::_Source
     end
   end

data/sig/collection/sources.rbs

@@ -9,16 +9,24 @@ module RBS
         def install: (dest: Pathname, config_entry: Config::gem_entry, stdout: CLI::_IO) -> void
         def to_lockfile: () -> source_entry
         def manifest_of: (Config::gem_entry) -> manifest_entry?
+        def dependencies_of: (Config::gem_entry) -> Array[{"name" => String}]?
       end
 
       type source_entry = Git::source_entry
-                            | Stdlib::source_entry
-                            | Rubygems::source_entry
+                        | Stdlib::source_entry
+                        | Rubygems::source_entry
+
       type manifest_entry = {
         "dependencies" => Array[{"name" => String}]?,
       }
 
+      module Base : _Source
+        def dependencies_of: (Config::gem_entry config_entry) -> Array[{"name" => String}]?
+      end
+
       class Git
+        include Base
+
         METADATA_FILENAME: String
 
         type source_entry = {
@@ -50,6 +58,10 @@ module RBS
 
         private
 
+        @git_dir: Pathname?
+
+        @resolved_revision: String?
+
         def _install: (dest: Pathname , config_entry: Config::gem_entry) -> void
 
         def cp_r: (Pathname, Pathname) -> void
@@ -77,6 +89,11 @@ module RBS
 
       # signatures that are bundled in rbs gem under the stdlib/ directory
       class Stdlib
+
+        REPO: Repository
+
+        include Base
+
         type source_entry =  {
           'type' => 'stdlib',
         }
@@ -84,7 +101,7 @@ module RBS
         # polyfill of singleton module
         def self.instance: () -> instance
 
-        def has?: (Config::gem_entry) -> bool
+        def has?: (Config::gem_entry) -> boolish
 
         def versions: (Config::gem_entry) -> Array[String]
 
@@ -96,11 +113,13 @@ module RBS
 
         private
 
-        def gem_dir: (Config::gem_entry) -> Pathname
+        def lookup: (Config::gem_entry) -> Pathname?
       end
 
       # sig/ directory
       class Rubygems
+        include Base
+
         type source_entry = {
           'type' => 'rubygems',
         }

data/sig/definition.rbs

@@ -69,6 +69,14 @@ module RBS
       def map_type_bound: () { (AST::TypeParam::bound) -> AST::TypeParam::bound } -> Method
 
       def map_method_type: () { (MethodType) -> MethodType } -> Method
+
+      def update: (
+        ?super_method: Method?,
+        ?defs: Array[TypeDef],
+        ?accessibility: accessibility,
+        ?alias_of: Method?,
+        ?annotations: Array[AST::Annotation]
+      ) -> Method
     end
 
     module Ancestor

data/sig/definition_builder.rbs

@@ -1,4 +1,15 @@
 module RBS
+  # DefinitionBuilder translates TypeName to Definition of the type
+  #
+  # The translation goes three steps:
+  #
+  # 1. Calculate _ancestors_ of the type with AncestorBuilder
+  # 2. Calculate _partial_ definitions of each ancestor
+  # 3. Merge _partial_ definitions
+  #
+  # A _partial_ definition is a definition of one type name, in terms of it doesn't have methods of super classes nor included modules.
+  #
+  #
   class DefinitionBuilder
     attr_reader env: Environment
     attr_reader type_name_resolver: TypeNameResolver
@@ -12,18 +23,23 @@ module RBS
 
     def initialize: (env: Environment, ?ancestor_builder: AncestorBuilder?, ?method_builder: MethodBuilder?) -> void
 
-    def validate_super_class!: (TypeName, Environment::ClassEntry) -> void
-
-    def ensure_namespace!: (Namespace, location: Location[untyped, untyped]?) -> void
-
     def build_interface: (TypeName) -> Definition
 
+    # Returns a Definition of a instance of given type name.
+    #
+    # If TypeName is a module and `no_self_types` is `true`, it won't have methods of _self type constraints_.
+    # This typically happens when definition is being calculated for mixin.
+    #
     def build_instance: (TypeName, ?no_self_types: bool) -> Definition
 
-    def build_singleton0: (TypeName) -> Definition
-
     def build_singleton: (TypeName) -> Definition
 
+    def validate_super_class!: (TypeName, Environment::ClassEntry) -> void
+
+    def ensure_namespace!: (Namespace, location: Location[untyped, untyped]?) -> void
+
+    def build_singleton0: (TypeName) -> Definition
+
     def merge_definition: (src: Definition, dest: Definition, subst: Substitution, ?implemented_in: :keep | TypeName | nil, ?keep_super: bool) -> void
 
     def merge_method: (TypeName, Hash[Symbol, Definition::Method], Symbol, Definition::Method, Substitution, ?implemented_in: :keep | TypeName | nil, ?keep_super: bool) -> void
@@ -41,7 +57,48 @@ module RBS
 
     def insert_variable: (TypeName, Hash[Symbol, Definition::Variable], name: Symbol, type: Types::t) -> void
 
-    def define_methods: (Definition, interface_methods: Hash[Symbol, Definition::Method], methods: MethodBuilder::Methods, super_interface_method: bool) -> void
+    # Add methods from `methods` to Definition
+    #
+    # * `methods`:
+    # * `interface_methods`: Methods of interfaces mixed into the type
+    # * `self_constraints_methods`: Methods of the self constraints methods
+    # * `super_interface_method`: `true` to have super method of existing method (`true` is the Definition is the target module)
+    #
+    def define_methods: (
+      Definition,
+      methods: MethodBuilder::Methods,
+      interface_methods: Hash[Symbol, Definition::Method],
+      methods_with_self: Hash[Symbol, Definition::Method]?,
+      super_interface_method: bool
+    ) -> void
+
+    # Define methods on singleton type
+    #
+    def define_methods_singleton: (
+      Definition,
+      methods: MethodBuilder::Methods,
+      interface_methods: Hash[Symbol, Definition::Method]
+    ) -> void
+
+    # Define methods on instance type
+    #
+    def define_methods_instance: (
+      Definition,
+      methods: MethodBuilder::Methods,
+      interface_methods: Hash[Symbol, Definition::Method]
+    ) -> void
+
+    # Define methods on module instance type
+    #
+    # * Pass `nil` to `module_self_methods:` to build a module instance type that will be mixed in to other modules/classes
+    # * Pass methods from self-type-constraints to build a module instance type alone (to type check itself)
+    #
+    def define_methods_module_instance: (
+      Definition,
+      methods: MethodBuilder::Methods,
+      interface_methods: Hash[Symbol, Definition::Method],
+      module_self_methods: Hash[Symbol, Definition::Method]?
+    ) -> void
 
     # Validates presence of type names recursively.
     # Assumes the type names are already resolved.

data/sig/environment.rbs

@@ -33,6 +33,8 @@ module RBS
       attr_reader name: TypeName
       attr_reader decls: Array[D[M]]
 
+      @primary: D[M]?
+
       def initialize: (name: TypeName) -> void
 
       def insert: (decl: M, outer: Array[module_decl]) -> void
@@ -115,6 +117,8 @@ module RBS
 
     def inspect: () -> String
 
+    @buffers: Array[Buffer]
+
     def buffers: () -> Array[Buffer]
 
     def buffers_decls: () -> Hash[Buffer, Array[AST::Declarations::t]]

data/sig/environment_loader.rbs

@@ -40,7 +40,7 @@ module RBS
     attr_reader core_root: Pathname?
     attr_reader repository: Repository
 
-    attr_reader libs: Array[Library]
+    attr_reader libs: Set[Library]
     attr_reader dirs: Array[Pathname]
 
     # The source where the RBS comes from.
@@ -76,7 +76,9 @@ module RBS
     # If RBS files cannot be found in the gem, it tries to load RBSs from repository.
     #
     def add: (path: Pathname) -> void
-           | (library: String, version: String?) -> void
+           | (library: String, version: String?, ?resolve_dependencies: boolish) -> void
+
+    def resolve_dependencies: (library: String, version: String?) -> void
 
     # Add repository path and libraries via rbs_collection.lock.yaml.
     def add_collection: (Collection::Config collection_config) -> void