Merge pull request #2670 from ruby/module-normalization

Normalize modules during type name resolution

Author: soutaro

Rakefile

@@ -25,8 +25,12 @@ test_config = lambda do |t|
   t.test_files = FileList["test/**/*_test.rb"].reject do |path|
     path =~ %r{test/stdlib/}
   end
-  t.verbose = true
-  t.options = '-v'
+  if defined?(RubyMemcheck)
+    if t.is_a?(RubyMemcheck::TestTask)
+      t.verbose = true
+      t.options = '-v'
+    end
+  end
 end
 
 Rake::TestTask.new(test: :compile, &test_config)
@@ -550,4 +554,4 @@ task :prepare_profiling do
   Rake::Task[:"clobber"].invoke
   Rake::Task[:"templates"].invoke
   Rake::Task[:"compile"].invoke
-end
+end

docs/aliases.md

@@ -0,0 +1,79 @@
+# Aliases
+
+This document explains module/class aliases and type aliases.
+
+## Module/class alias
+
+Module/class aliases give another name to a module/class.
+This is useful for some syntaxes that has lexical constraints.
+
+```rbs
+class C
+end
+
+class D = C         # ::D is an alias for ::C
+
+class E < D         # ::E inherits from ::D, which is actually ::C
+end
+```
+
+Note that module/class aliases cannot be recursive.
+
+So, we can define a *normalization* of aliased module/class names.
+Normalization follows the chain of alias definitions and resolves them to the original module/class defined with `module`/`class` syntax.
+
+```rbs
+class C
+end
+
+class D = C
+class E = D
+```
+
+`::E` is defined as an alias, and it can be normalized to `::C`.
+
+## Type alias
+
+The biggest difference from module/class alias is that type alias can be recursive.
+
+```rbs
+# cons_cell type is defined recursively
+type cons_cell = nil
+               | [Integer, cons_cell]
+```
+
+This means type aliases *cannot be* normalized generally.
+So, we provide another operation for type alias, `DefinitionBuilder#expand_alias` and its family.
+It substitutes with the immediate right hand side of a type alias.
+
+```
+cons_cell ===> nil | [Integer, cons_cell]                   (expand 1 step)
+          ===> nil | [Integer, nil | [Integer, cons_cell]]  (expand 2 steps)
+          ===> ...                                          (expand will go infinitely)
+```
+
+Note that the namespace of a type alias *can be* normalized, because they are module names.
+
+```rbs
+module M
+  type t = String
+end
+
+module N = M
+```
+
+With the type definition above, a type `::N::t` can be normalized to `::M::t`.
+And then it can be expanded to `::String`.
+
+> [!NOTE]
+> This is something like an *unfold* operation in type theory.
+
+## Type name resolution
+
+Type name resolution in RBS usually rewrites *relative* type names to *absolute* type names.
+`Environment#resolve_type_names` converts all type names in the RBS type definitions, and returns a new `Environment` object.
+
+It also *normalizes* modules names in type names.
+
+- If the type name can be resolved and normalized successfully, the AST has *absolute* type names.
+- If the type name resolution/normalization fails, the AST has *relative* type names.

lib/rbs/cli/validate.rb

@@ -137,7 +137,7 @@ def validate_class_module_definition
 
                 self_params =
                   if self_type.name.class?
-                    @env.normalized_module_entry(self_type.name)&.type_params
+                    @env.module_entry(self_type.name, normalized: true)&.type_params
                   else
                     @env.interface_decls[self_type.name]&.decl&.type_params
                   end
@@ -186,7 +186,7 @@ def validate_class_module_definition
                 when AST::Members::Mixin
                   params =
                     if member.name.class?
-                      module_decl = @env.normalized_module_entry(member.name) or raise
+                      module_decl = @env.module_entry(member.name, normalized: true) or raise
                       module_decl.type_params
                     else
                       interface_decl = @env.interface_decls.fetch(member.name)

lib/rbs/definition_builder/ancestor_builder.rb

@@ -220,7 +220,7 @@ def one_instance_ancestors(type_name)
               InvalidTypeApplicationError.check2!(type_name: super_class.name, args: super_class.args, env: env, location: super_class.location)
             end
 
-            super_entry = env.normalized_class_entry(super_name) or raise
+            super_entry = env.class_entry(super_name, normalized: true) or raise
             super_args = AST::TypeParam.normalize_args(super_entry.type_params, super_args)
 
             ancestors = OneAncestors.class_instance(
@@ -248,7 +248,7 @@ def one_instance_ancestors(type_name)
 
               module_name = module_self.name
               if module_name.class?
-                module_entry = env.normalized_module_class_entry(module_name) or raise
+                module_entry = env.module_class_entry(module_name, normalized: true) or raise
                 module_name = module_entry.name
                 self_args = AST::TypeParam.normalize_args(module_entry.type_params, module_self.args)
               end
@@ -361,7 +361,7 @@ def mixin_ancestors0(decl, type_name, align_params:, included_modules:, included
                 MixinClassError.check!(type_name: type_name, env: env, member: member)
                 NoMixinFoundError.check!(member.name, env: env, member: member)
 
-                module_decl = env.normalized_module_entry(module_name) or raise
+                module_decl = env.module_entry(module_name, normalized: true) or raise
                 module_args = AST::TypeParam.normalize_args(module_decl.type_params, module_args)
 
                 module_name = env.normalize_module_name(module_name)
@@ -380,7 +380,7 @@ def mixin_ancestors0(decl, type_name, align_params:, included_modules:, included
                 MixinClassError.check!(type_name: type_name, env: env, member: member)
                 NoMixinFoundError.check!(member.name, env: env, member: member)
 
-                module_decl = env.normalized_module_entry(member.name) or raise
+                module_decl = env.module_entry(member.name, normalized: true) or raise
                 module_name = module_decl.name
 
                 module_args = member.args.map {|type| align_params ? type.sub(align_params) : type }
@@ -398,7 +398,7 @@ def mixin_ancestors0(decl, type_name, align_params:, included_modules:, included
                 MixinClassError.check!(type_name: type_name, env: env, member: member)
                 NoMixinFoundError.check!(member.name, env: env, member: member)
 
-                module_decl = env.normalized_module_entry(module_name) or raise
+                module_decl = env.module_entry(module_name, normalized: true) or raise
                 module_args = AST::TypeParam.normalize_args(module_decl.type_params, module_args)
 
                 module_name = env.normalize_module_name(module_name)
@@ -427,7 +427,7 @@ def mixin_ancestors0(decl, type_name, align_params:, included_modules:, included
                 end
 
                 # Check if module exists
-                module_decl = env.normalized_module_entry(module_name) or raise NoMixinFoundError.new(type_name: module_name, member: member)
+                module_decl = env.module_entry(module_name, normalized: true) or raise NoMixinFoundError.new(type_name: module_name, member: member)
                 module_args = AST::TypeParam.normalize_args(module_decl.type_params, module_args)
                 module_name = env.normalize_module_name(module_name)
                 included_modules << Definition::Ancestor::Instance.new(name: module_name, args: module_args, source: member)
@@ -444,7 +444,7 @@ def mixin_ancestors0(decl, type_name, align_params:, included_modules:, included
                 end
 
                 # Check if module exists
-                module_decl = env.normalized_module_entry(module_name) or raise NoMixinFoundError.new(type_name: module_name, member: member)
+                module_decl = env.module_entry(module_name, normalized: true) or raise NoMixinFoundError.new(type_name: module_name, member: member)
                 module_args = AST::TypeParam.normalize_args(module_decl.type_params, module_args)
                 module_name = env.normalize_module_name(module_name)
                 extended_modules << Definition::Ancestor::Instance.new(name: module_name, args: module_args, source: member)
@@ -461,7 +461,7 @@ def mixin_ancestors0(decl, type_name, align_params:, included_modules:, included
                 end
 
                 # Check if module exists
-                module_decl = env.normalized_module_entry(module_name) or raise NoMixinFoundError.new(type_name: module_name, member: member)
+                module_decl = env.module_entry(module_name, normalized: true) or raise NoMixinFoundError.new(type_name: module_name, member: member)
                 module_args = AST::TypeParam.normalize_args(module_decl.type_params, module_args)
                 module_name = env.normalize_module_name(module_name)
                 prepended_modules << Definition::Ancestor::Instance.new(name: module_name, args: module_args, source: member)

lib/rbs/environment.rb

@@ -122,21 +122,17 @@ def class_alias?(name)
       end
     end
 
-    def class_entry(type_name)
-      case
-      when (class_entry = class_decls[type_name]).is_a?(ClassEntry)
-        class_entry
-      when (class_alias = class_alias_decls[type_name]).is_a?(ClassAliasEntry)
-        class_alias
+    def class_entry(type_name, normalized: false)
+      case entry = constant_entry(type_name, normalized: normalized || false)
+      when ClassEntry, ClassAliasEntry
+        entry
       end
     end
 
-    def module_entry(type_name)
-      case
-      when (module_entry = class_decls[type_name]).is_a?(ModuleEntry)
-        module_entry
-      when (module_alias = class_alias_decls[type_name]).is_a?(ModuleAliasEntry)
-        module_alias
+    def module_entry(type_name, normalized: false)
+      case entry = constant_entry(type_name, normalized: normalized || false)
+      when ModuleEntry, ModuleAliasEntry
+        entry
       end
     end
 
@@ -152,26 +148,40 @@ def normalized_class_entry(type_name)
     end
 
     def normalized_module_entry(type_name)
-      if name = normalize_module_name?(type_name)
-        case entry = module_entry(name)
-        when ModuleEntry, nil
-          entry
-        when ModuleAliasEntry
-          raise
-        end
-      end
+      module_entry(type_name, normalized: true)
     end
 
-    def module_class_entry(type_name)
-      class_entry(type_name) || module_entry(type_name)
+    def module_class_entry(type_name, normalized: false)
+      entry = constant_entry(type_name, normalized: normalized || false)
+      if entry.is_a?(ConstantEntry)
+        nil
+      else
+        entry
+      end
     end
 
     def normalized_module_class_entry(type_name)
-      normalized_class_entry(type_name) || normalized_module_entry(type_name)
+      module_class_entry(type_name, normalized: true)
     end
 
-    def constant_entry(type_name)
-      class_entry(type_name) || module_entry(type_name) || constant_decls[type_name]
+    def constant_entry(type_name, normalized: false)
+      if normalized
+        if normalized_name = normalize_module_name?(type_name)
+          class_decls.fetch(normalized_name, nil)
+        else
+          # The type_name may be declared with constant declaration
+          unless type_name.namespace.empty?
+            parent = type_name.namespace.to_type_name
+            normalized_parent = normalize_module_name?(parent) or return
+            constant_name = TypeName.new(name: type_name.name, namespace: normalized_parent.to_namespace)
+            constant_decls.fetch(constant_name, nil)
+          end
+        end
+      else
+        class_decls.fetch(type_name, nil) ||
+          class_alias_decls.fetch(type_name, nil) ||
+          constant_decls.fetch(type_name, nil)
+      end
     end
 
     def normalize_type_name?(name)
@@ -206,6 +216,10 @@ def normalize_type_name!(name)
       end
     end
 
+    def normalize_type_name(name)
+      normalize_type_name?(name) || name
+    end
+
     def normalized_type_name?(type_name)
       case
       when type_name.interface?
@@ -220,53 +234,44 @@ def normalized_type_name?(type_name)
     end
 
     def normalized_type_name!(name)
-      normalized_type_name?(name) or raise "Normalized type name is expected but given `#{name}`, which is normalized to `#{normalize_type_name?(name)}`"
+      normalized_type_name?(name) or raise "Normalized type name is expected but given `#{name}`"
       name
     end
 
-    def normalize_type_name(name)
-      normalize_type_name?(name) || name
-    end
-
-    def normalize_module_name(name)
-      normalize_module_name?(name) or name
-    end
-
     def normalize_module_name?(name)
       raise "Class/module name is expected: #{name}" unless name.class?
       name = name.absolute! unless name.absolute?
 
-      if @normalize_module_name_cache.key?(name)
-        return @normalize_module_name_cache[name]
+      original_name = name
+
+      if @normalize_module_name_cache.key?(original_name)
+        return @normalize_module_name_cache[original_name]
       end
 
-      unless name.namespace.empty?
-        parent = name.namespace.to_type_name
-        if normalized_parent = normalize_module_name?(parent)
-          type_name = TypeName.new(namespace: normalized_parent.to_namespace, name: name.name)
-        else
-          @normalize_module_name_cache[name] = nil
-          return
+      if alias_entry = class_alias_decls.fetch(name, nil)
+        unless alias_entry.decl.old_name.absolute?
+          # Having relative old_name means the type name resolution was failed.
+          # Run TypeNameResolver for failure reason
+          resolver = Resolver::TypeNameResolver.build(self)
+          name = resolver.resolve_namespace(name, context: nil)
+          @normalize_module_name_cache[original_name] = name
+          return name
         end
-      else
-        type_name = name
-      end
 
-      @normalize_module_name_cache[name] = false
+        name = alias_entry.decl.old_name
+      end
 
-      entry = constant_entry(type_name)
+      if class_decls.key?(name)
+        @normalize_module_name_cache[original_name] = name
+      end
+    end
 
-      normalized_type_name =
-        case entry
-        when ClassEntry, ModuleEntry
-          type_name
-        when ClassAliasEntry, ModuleAliasEntry
-          normalize_module_name?(entry.decl.old_name)
-        else
-          nil
-        end
+    def normalize_module_name(name)
+      normalize_module_name?(name) || name
+    end
 
-      @normalize_module_name_cache[name] = normalized_type_name
+    def normalize_module_name!(name)
+      normalize_module_name?(name) or raise "Module name `#{name}` cannot be normalized"
     end
 
     def insert_rbs_decl(decl, context:, namespace:)
@@ -515,7 +520,7 @@ def resolve_signature(resolver, table, dirs, decls, only: nil)
     end
 
     def resolve_type_names(only: nil)
-      resolver = Resolver::TypeNameResolver.new(self)
+      resolver = Resolver::TypeNameResolver.build(self)
       env = Environment.new
 
       table = UseMap::Table.new()

lib/rbs/errors.rb

@@ -93,7 +93,7 @@ def self.check2!(env:, type_name:, args:, location:)
       params =
         case
         when type_name.class?
-          decl = env.normalized_module_class_entry(type_name) or raise
+          decl = env.module_class_entry(type_name, normalized: true) or raise
           decl.type_params
         when type_name.interface?
           env.interface_decls.fetch(type_name).decl.type_params
@@ -491,7 +491,7 @@ def self.check!(type_name:, env:, member:)
              else
                raise "Unknown member type: #{member.class}"
              end
-      
+
       if env.class_decl?(name)
         raise new(type_name: type_name, member: member)
       end