mt-lang 0.3.17 → 0.3.20

data/lib/milk_tea/core/semantic_analyzer/calls.rb

@@ -645,22 +645,13 @@ module MilkTea
         )
       end
 
-      def event_method_kind(receiver_type, name)
-        return unless event_type?(receiver_type)
+      def specialized_receiver_method_kind(receiver_type, name)
+        SPECIALIZED_RECEIVERS.each_value do |spec|
+          next unless send(spec[:predicate], receiver_type)
 
-        EVENT_METHOD_KINDS[name]
-      end
-
-      def atomic_method_kind(receiver_type, name)
-        return unless atomic_type?(receiver_type)
-
-        ATOMIC_METHOD_KINDS[name]
-      end
-
-      def simd_method_kind(receiver_type, name)
-        return unless simd_type?(receiver_type)
-
-        SIMD_METHOD_KINDS[name]
+          return spec[:kinds][name]
+        end
+        nil
       end
 
       def check_atomic_method_call(kind, receiver_type, receiver, arguments, scopes:)
@@ -750,8 +741,8 @@ module MilkTea
 
         case expression
         when AST::Call
-          callable_kind, callable, _receiver = resolve_callable(expression.callee, scopes:)
-          callable_kind == :struct && callable == target_type
+          resolution = resolve_callable(expression.callee, scopes:)
+          resolution.kind == :struct && resolution.value == target_type
         when AST::Specialization
           return false unless expression.callee.is_a?(AST::Identifier)
           return false unless %w[zero default].include?(expression.callee.name)
@@ -772,12 +763,6 @@ module MilkTea
         name == "as_str" || name == "as_cstr"
       end
 
-      def str_buffer_method_kind(receiver_type, name)
-        return unless str_buffer_type?(receiver_type)
-
-        STR_BUFFER_METHOD_KINDS[name]
-      end
-
       def str_buffer_method_name(kind)
         STR_BUFFER_METHOD_NAMES.fetch(kind)
       end
@@ -1032,42 +1017,50 @@ module MilkTea
           end
         end
 
-        fill_parameter_defaults!(by_position, params, binding, context_name)
+        fill_parameter_defaults!(by_position, params, binding)
 
         by_position.reject(&:nil?)
       end
 
-      def fill_parameter_defaults!(by_position, params, binding, context_name)
+      def fill_parameter_defaults!(by_position, params, binding)
         return unless binding
 
         ast_params = binding.ast.params
-        return unless ast_params.any? { |p| p.respond_to?(:default_value) && p.default_value }
+        return unless ast_params.any? { |p| param_has_default?(p) }
 
         params.each_with_index do |param, idx|
           next unless by_position[idx].nil?
           next unless idx < ast_params.length
 
           ast_param = ast_params[idx]
-          next unless ast_param.respond_to?(:default_value) && ast_param.default_value
+          next unless param_has_default?(ast_param)
 
-          by_position[idx] = AST::Argument.new(name: nil, value: ast_param.default_value)
+          by_position[idx] = default_arg_for(ast_param)
         end
       end
 
       def fill_positional_defaults!(arguments, binding)
-        return unless binding.ast.params.any? { |p| p.respond_to?(:default_value) && p.default_value }
+        return unless binding.ast.params.any? { |p| param_has_default?(p) }
 
         ast_params = binding.ast.params
         while arguments.length < ast_params.length
           ast_param = ast_params[arguments.length]
-          if ast_param.respond_to?(:default_value) && ast_param.default_value
-            arguments << AST::Argument.new(name: nil, value: ast_param.default_value)
+          if param_has_default?(ast_param)
+            arguments << default_arg_for(ast_param)
           else
             break
           end
         end
       end
 
+      def param_has_default?(ast_param)
+        ast_param.respond_to?(:default_value) && ast_param.default_value
+      end
+
+      def default_arg_for(ast_param)
+        AST::Argument.new(name: nil, value: ast_param.default_value)
+      end
+
       def count_required_params(binding)
         return binding.type.params.length unless binding.ast.params.any? { |p| p.respond_to?(:default_value) && p.default_value }
 

data/lib/milk_tea/core/semantic_analyzer/expressions.rb

@@ -199,8 +199,8 @@ module MilkTea
           when AST::Specialization
             if expression.callee.is_a?(AST::Identifier)
               if expression.callee.name == "zero"
-                callable_kind, callable, = resolve_callable(expression, scopes:)
-                return check_zero_call(callable, [], expected_type:) if callable_kind == :zero
+                resolution = resolve_callable(expression, scopes:)
+                return check_zero_call(resolution.value, [], expected_type:) if resolution.kind == :zero
               end
 
               if expression.callee.name == "default"
@@ -397,10 +397,7 @@ module MilkTea
         if char_array_removed_text_method?(method_receiver_type, expression.member)
           raise_sema_error("#{method_receiver_type}.#{expression.member} is not available; array[char, N] is raw storage, use str_buffer[N] or an explicit helper")
         end
-        if str_buffer_type?(method_receiver_type) && str_buffer_method_kind(method_receiver_type, expression.member)
-          raise_sema_error("method #{method_receiver_type}.#{expression.member} must be called")
-        end
-        if event_type?(method_receiver_type) && event_method_kind(method_receiver_type, expression.member)
+        if specialized_receiver_method_kind(method_receiver_type, expression.member)
           raise_sema_error("method #{method_receiver_type}.#{expression.member} must be called")
         end
 
@@ -923,7 +920,10 @@ module MilkTea
       end
 
       def infer_call(expression, scopes:, expected_type: nil)
-        callable_kind, callable, receiver = resolve_callable(expression.callee, scopes:)
+        resolution = resolve_callable(expression.callee, scopes:)
+        callable_kind = resolution.kind
+        callable = resolution.value
+        receiver = resolution.receiver
         @resolved_call_kinds[@ctx.ast.node_ids[expression.callee.object_id]] = callable_kind
 
         case callable_kind
@@ -1152,7 +1152,9 @@ module MilkTea
         call = expression
         return unless call.is_a?(AST::Call)
 
-        callable_kind, callable, _receiver = resolve_callable(call.callee, scopes:)
+        resolution = resolve_callable(call.callee, scopes:)
+        callable_kind = resolution.kind
+        callable = resolution.value
         return unless callable_kind == :function
 
         callable = specialize_function_binding(
@@ -1245,6 +1247,11 @@ module MilkTea
       end
 
       def resolve_callable(callee, scopes:)
+        kind, value, receiver = resolve_callable_raw(callee, scopes:)
+        CallableResolution.new(kind:, value:, receiver:)
+      end
+
+      def resolve_callable_raw(callee, scopes:)
         case callee
         when AST::Identifier
           if (binding = lookup_value(callee.name, scopes))
@@ -1343,20 +1350,8 @@ module MilkTea
             raise_sema_error("#{method_receiver_type}.#{callee.member} is not available; array[char, N] is raw storage, use str_buffer[N] or an explicit helper")
           end
 
-          if (str_buffer_method = str_buffer_method_kind(method_receiver_type, callee.member))
-            return [str_buffer_method, method_receiver_type, callee.receiver]
-          end
-
-          if (event_method = event_method_kind(method_receiver_type, callee.member))
-            return [event_method, method_receiver_type, callee.receiver]
-          end
-
-          if (atomic_method = atomic_method_kind(method_receiver_type, callee.member))
-            return [atomic_method, method_receiver_type, callee.receiver]
-          end
-
-          if (simd_method = simd_method_kind(method_receiver_type, callee.member))
-            return [simd_method, method_receiver_type, callee.receiver]
+          if (kind = specialized_receiver_method_kind(method_receiver_type, callee.member))
+            return [kind, method_receiver_type, callee.receiver]
           end
 
           field_receiver_type = infer_field_receiver_type(callee.receiver, scopes:)
@@ -1574,7 +1569,9 @@ module MilkTea
       end
 
       def resolve_callable_handle_argument(expression, scopes:)
-        callable_kind, callable, _receiver = resolve_callable(expression, scopes:)
+        resolution = resolve_callable(expression, scopes:)
+        callable_kind = resolution.kind
+        callable = resolution.value
         raise_sema_error("callable_of expects a callable declaration name") unless callable_kind == :function
 
         Types::CallableHandle.new(describe_expression(expression), callable.ast)

data/lib/milk_tea/core/semantic_analyzer/name_resolution.rb

@@ -211,123 +211,148 @@ module MilkTea
 
       def resolve_non_nullable_type(type_ref, type_params: {}, type_param_constraints: {}, nested_types: nil)
         if type_ref.is_a?(AST::FunctionType)
-          params = type_ref.params.map do |param|
-            Types::Registry.parameter(param.name, resolve_type_ref(param.type, type_params:, type_param_constraints:))
-          end
-          return Types::Registry.function(nil, params:, return_type: resolve_type_ref(type_ref.return_type, type_params:, type_param_constraints:))
+          return resolve_function_type_ref(type_ref, type_params:, type_param_constraints:)
         end
 
         if type_ref.is_a?(AST::ProcType)
-          params = type_ref.params.map do |param|
-            Types::Registry.parameter(param.name, resolve_type_ref(param.type, type_params:, type_param_constraints:))
-          end
-          return Types::Registry.proc(params:, return_type: resolve_type_ref(type_ref.return_type, type_params:, type_param_constraints:))
+          return resolve_proc_type_ref(type_ref, type_params:, type_param_constraints:)
         end
 
         if type_ref.is_a?(AST::DynType)
-          interface = resolve_interface_ref(type_ref.interface)
-          raise_sema_error("generic interface #{interface.name} requires type arguments") if interface.is_a?(GenericInterfaceBinding)
-          type_arguments = interface.type_arguments || []
-          type = Types::Dyn.new(interface, type_arguments)
-          type = Types::Registry.nullable(type) if type_ref.nullable
-          return type
+          return resolve_dyn_type_ref(type_ref)
         end
 
         if type_ref.is_a?(AST::TupleType)
-          names = []
-          element_types = []
-          type_ref.element_types.each do |et|
-            if et.is_a?(AST::Argument)
-              names << et.name
-              element_types << resolve_type_ref(et.value, type_params:, type_param_constraints:)
-            else
-              names << nil
-              element_types << resolve_type_ref(et, type_params:, type_param_constraints:)
-            end
-          end
-          has_named = names.any?
-          return Types::Registry.tuple(element_types, field_names: has_named ? names : nil)
+          return resolve_tuple_type_ref(type_ref, type_params:, type_param_constraints:)
         end
 
         parts = type_ref.name.parts
 
         if type_ref.arguments.any?
-          name = parts.join(".")
-          arguments = type_ref.arguments.map { |argument| resolve_type_argument(argument.value, type_params:, type_param_constraints:) }
-
-          if name != "ref" && arguments.any? { |argument| contains_ref_type?(argument) && !stored_ref_supported_type?(argument) }
-            raise_sema_error("ref types cannot be nested inside #{name}", type_ref)
-          end
+          return resolve_generic_instance_type_ref(type_ref, parts, type_params:, type_param_constraints:)
+        end
 
-          if name == "Task"
-            validate_generic_type!(name, arguments)
-            return Types::Registry.task(arguments[0])
-          end
+        if parts.length == 1 && type_ref.lifetime
+          raise_sema_error("lifetime annotations are only valid on ref types, got #{type_ref.name}", type_ref)
+        end
 
-          if (generic_type = resolve_named_generic_type(parts))
-            begin
-              validate_generic_type_param_constraints!(generic_type, arguments, context: "type #{generic_type}", available_type_param_constraints: type_param_constraints)
-              return generic_type.instantiate(arguments)
-            rescue ArgumentError => error
-              raise_sema_error(error.message)
-            end
-          end
+        if parts.length == 1
+          return resolve_single_part_type_ref(type_ref, parts.first, nested_types:, type_params:)
+        end
 
-          # Handle types with lifetime params only (no type params)
-          if arguments.all? { |a| a.is_a?(Types::LifetimeRef) }
-            type = @ctx.types[name]
-            if type.is_a?(Types::Struct) && type.lifetime_params&.any?
-              lifetime_args = arguments.select { |a| a.is_a?(Types::LifetimeRef) }.map(&:name)
-              if lifetime_args.to_set == type.lifetime_params.to_set
-                return type
-              end
-            end
-          end
+        resolve_multi_part_type_ref(type_ref, parts)
+      end
 
-          validate_generic_type!(name, arguments)
-          return Types::Registry.span(arguments.first) if name == "span"
+      def resolve_function_type_ref(type_ref, type_params:, type_param_constraints:)
+        params = type_ref.params.map do |param|
+          Types::Registry.parameter(param.name, resolve_type_ref(param.type, type_params:, type_param_constraints:))
+        end
+        Types::Registry.function(nil, params:, return_type: resolve_type_ref(type_ref.return_type, type_params:, type_param_constraints:))
+      end
 
-          return Types::Registry.soa(arguments[0], count: arguments[1].value) if name == "SoA"
+      def resolve_proc_type_ref(type_ref, type_params:, type_param_constraints:)
+        params = type_ref.params.map do |param|
+          Types::Registry.parameter(param.name, resolve_type_ref(param.type, type_params:, type_param_constraints:))
+        end
+        Types::Registry.proc(params:, return_type: resolve_type_ref(type_ref.return_type, type_params:, type_param_constraints:))
+      end
 
-          return Types::Registry.simd(arguments[0], lane_count: arguments[1].value) if name == "simd"
+      def resolve_dyn_type_ref(type_ref)
+        interface = resolve_interface_ref(type_ref.interface)
+        raise_sema_error("generic interface #{interface.name} requires type arguments") if interface.is_a?(GenericInterfaceBinding)
+        type_arguments = interface.type_arguments || []
+        type = Types::Dyn.new(interface, type_arguments)
+        type = Types::Registry.nullable(type) if type_ref.nullable
+        type
+      end
 
-          arguments = [type_ref.lifetime] + arguments if name == "ref" && type_ref.lifetime
-          return Types::Registry.generic_instance(name, arguments)
+      def resolve_tuple_type_ref(type_ref, type_params:, type_param_constraints:)
+        names = []
+        element_types = []
+        type_ref.element_types.each do |et|
+          if et.is_a?(AST::Argument)
+            names << et.name
+            element_types << resolve_type_ref(et.value, type_params:, type_param_constraints:)
+          else
+            names << nil
+            element_types << resolve_type_ref(et, type_params:, type_param_constraints:)
+          end
         end
+        has_named = names.any?
+        Types::Registry.tuple(element_types, field_names: has_named ? names : nil)
+      end
 
-        if parts.length == 1 && type_ref.lifetime
-          raise_sema_error("lifetime annotations are only valid on ref types, got #{type_ref.name}", type_ref)
-        end
+      def resolve_generic_instance_type_ref(type_ref, parts, type_params:, type_param_constraints:)
+        name = parts.join(".")
+        arguments = type_ref.arguments.map { |argument| resolve_type_argument(argument.value, type_params:, type_param_constraints:) }
 
-        if parts.length == 1
-          return type_params.fetch(parts.first) if type_params.key?(parts.first)
+        if name != "ref" && arguments.any? { |argument| contains_ref_type?(argument) && !stored_ref_supported_type?(argument) }
+          raise_sema_error("ref types cannot be nested inside #{name}", type_ref)
+        end
 
-          if nested_types && (type = nested_types[parts.first])
-            return type
-          end
+        if name == "Task"
+          validate_generic_type!(name, arguments)
+          return Types::Registry.task(arguments[0])
+        end
 
-          if parts.first.start_with?("@")
-            raise_sema_error("unknown lifetime #{parts.first}", type_ref)
+        if (generic_type = resolve_named_generic_type(parts))
+          begin
+            validate_generic_type_param_constraints!(generic_type, arguments, context: "type #{generic_type}", available_type_param_constraints: type_param_constraints)
+            return generic_type.instantiate(arguments)
+          rescue ArgumentError => error
+            raise_sema_error(error.message)
           end
+        end
 
-          type = @ctx.types[parts.first]
-          unless type
-            type_names = @ctx.types.keys
-            suggestion = suggest_name(parts.first, type_names)
-            unless suggestion
-              suggestion = import_suggestion_for_type(parts.first)
+        if arguments.all? { |a| a.is_a?(Types::LifetimeRef) }
+          type = @ctx.types[name]
+          if type.is_a?(Types::Struct) && type.lifetime_params&.any?
+            lifetime_args = arguments.select { |a| a.is_a?(Types::LifetimeRef) }.map(&:name)
+            if lifetime_args.to_set == type.lifetime_params.to_set
+              return type
             end
-            raise_sema_error("unknown type #{parts.first}", type_ref, suggestion: suggestion ? "did you mean '#{suggestion}'?" : nil)
           end
-          raise_sema_error("generic type #{parts.first} requires type arguments", type_ref) if type.is_a?(Types::GenericStructDefinition) || type.is_a?(Types::GenericVariantDefinition)
+        end
+
+        validate_generic_type!(name, arguments)
+        return Types::Registry.span(arguments.first) if name == "span"
+
+        return Types::Registry.soa(arguments[0], count: arguments[1].value) if name == "SoA"
+
+        return Types::Registry.simd(arguments[0], lane_count: arguments[1].value) if name == "simd"
+
+        arguments = [type_ref.lifetime] + arguments if name == "ref" && type_ref.lifetime
+        Types::Registry.generic_instance(name, arguments)
+      end
+
+      def resolve_single_part_type_ref(type_ref, name, nested_types:, type_params:)
+        return type_params.fetch(name) if type_params.key?(name)
 
+        if nested_types && (type = nested_types[name])
           return type
         end
 
-        if parts.length >= 2
-          type = resolve_nested_type_ref(parts)
-          return type if type
+        if name.start_with?("@")
+          raise_sema_error("unknown lifetime #{name}", type_ref)
+        end
+
+        type = @ctx.types[name]
+        unless type
+          type_names = @ctx.types.keys
+          suggestion = suggest_name(name, type_names)
+          unless suggestion
+            suggestion = import_suggestion_for_type(name)
+          end
+          raise_sema_error("unknown type #{name}", type_ref, suggestion: suggestion ? "did you mean '#{suggestion}'?" : nil)
         end
+        raise_sema_error("generic type #{name} requires type arguments", type_ref) if type.is_a?(Types::GenericStructDefinition) || type.is_a?(Types::GenericVariantDefinition)
+
+        type
+      end
+
+      def resolve_multi_part_type_ref(type_ref, parts)
+        type = resolve_nested_type_ref(parts)
+        return type if type
 
         if parts.length == 2 && @ctx.imports.key?(parts.first)
           imported_module = @ctx.imports.fetch(parts.first)
@@ -386,12 +411,19 @@ module MilkTea
       def resolve_type_argument_ref(type_ref, type_params:, type_param_constraints:)
         return resolve_type_ref(type_ref, type_params:, type_param_constraints:) unless literal_type_argument_name_candidate?(type_ref)
 
-        resolve_type_ref(type_ref, type_params:, type_param_constraints:)
-      rescue SemanticError => error
+        result = try_resolve_type_ref(type_ref, type_params:, type_param_constraints:)
+        return result if result
+
         literal_type_argument = resolve_named_literal_type_argument(type_ref)
         return literal_type_argument if literal_type_argument
 
-        raise error
+        resolve_type_ref(type_ref, type_params:, type_param_constraints:)
+      end
+
+      def try_resolve_type_ref(type_ref, type_params:, type_param_constraints:)
+        resolve_type_ref(type_ref, type_params:, type_param_constraints:)
+      rescue SemanticError
+        nil
       end
 
       def literal_type_argument_name_candidate?(type_ref)

data/lib/milk_tea/core/semantic_analyzer/statements.rb

@@ -555,30 +555,32 @@ module MilkTea
         end
       end
 
+      MATCH_STMT_DISPATCH = [
+        [Types::Enum,       :each_enum_match_arm,    true],
+        [Types::Variant,    :each_variant_match_arm, true],
+        [:integer,          :each_integer_match_arm, false],
+        [Types::StringView, :each_string_match_arm,  false],
+        [Types::Tuple,      :each_tuple_match_arm,   false],
+      ].freeze
+
       def check_match_stmt(statement, scopes:, return_type:, allow_return:)
         validate_consuming_foreign_expression!(statement.expression, scopes:, root_allowed: false)
         scrutinee_type = infer_expression(statement.expression, scopes:)
+
         if error_type?(scrutinee_type)
-          check_recovered_match_stmt(statement, scopes:, return_type:, allow_return:)
-        elsif scrutinee_type.is_a?(Types::Enum)
-          check_enum_match_stmt(statement, scrutinee_type, scopes:, return_type:, allow_return:)
-        elsif scrutinee_type.is_a?(Types::Variant)
-          check_variant_match_stmt(statement, scrutinee_type, scopes:, return_type:, allow_return:)
-        elsif integer_type?(scrutinee_type)
-          check_integer_match_stmt(statement, scrutinee_type, scopes:, return_type:, allow_return:)
-        elsif scrutinee_type.is_a?(Types::StringView)
-          check_string_match_stmt(statement, scrutinee_type, scopes:, return_type:, allow_return:)
-        elsif scrutinee_type.is_a?(Types::Tuple)
-          check_tuple_match_stmt(statement, scrutinee_type, scopes:, return_type:, allow_return:)
-        else
-          raise_sema_error("match requires an enum, variant, or integer scrutinee, got #{scrutinee_type}")
+          return check_recovered_match_stmt(statement, scopes:, return_type:, allow_return:)
         end
-      end
 
-      def check_enum_match_stmt(statement, scrutinee_type, scopes:, return_type:, allow_return:)
-        each_enum_match_arm(statement, scrutinee_type, scopes:) do |arm, arm_scopes|
-          check_block(arm.body, scopes: arm_scopes, return_type:, allow_return:)
+        MATCH_STMT_DISPATCH.each do |type_class, arm_method, per_arm_scopes|
+          next unless type_class == :integer ? integer_type?(scrutinee_type) : scrutinee_type.is_a?(type_class)
+
+          send(arm_method, statement, scrutinee_type, scopes:) do |arm, arm_scopes|
+            check_block(arm.body, scopes: per_arm_scopes ? arm_scopes : scopes, return_type:, allow_return:)
+          end
+          return
         end
+
+        raise_sema_error("match requires an enum, variant, or integer scrutinee, got #{scrutinee_type}")
       end
 
       def each_enum_match_arm(statement, scrutinee_type, scopes:)
@@ -746,24 +748,6 @@ module MilkTea
         end
       end
 
-      def check_integer_match_stmt(statement, scrutinee_type, scopes:, return_type:, allow_return:)
-        each_integer_match_arm(statement, scrutinee_type, scopes:) do |arm|
-          check_block(arm.body, scopes:, return_type:, allow_return:)
-        end
-      end
-
-      def check_string_match_stmt(statement, scrutinee_type, scopes:, return_type:, allow_return:)
-        each_string_match_arm(statement, scrutinee_type, scopes:) do |arm|
-          check_block(arm.body, scopes:, return_type:, allow_return:)
-        end
-      end
-
-      def check_tuple_match_stmt(statement, scrutinee_type, scopes:, return_type:, allow_return:)
-        each_tuple_match_arm(statement, scrutinee_type, scopes:) do |arm|
-          check_block(arm.body, scopes:, return_type:, allow_return:)
-        end
-      end
-
       def wildcard_pattern?(expression)
         expression.is_a?(AST::Identifier) && expression.name == "_"
       end
@@ -810,12 +794,6 @@ module MilkTea
           failure_fields && failure_fields.length == 1 && failure_fields.key?("error")
       end
 
-      def check_variant_match_stmt(statement, scrutinee_type, scopes:, return_type:, allow_return:)
-        each_variant_match_arm(statement, scrutinee_type, scopes:) do |arm, arm_scopes|
-          check_block(arm.body, scopes: arm_scopes, return_type:, allow_return:)
-        end
-      end
-
       def each_variant_match_arm(statement, scrutinee_type, scopes:)
         covered_arms = {}
         wildcard_seen = false

data/lib/milk_tea/core/semantic_analyzer.rb

@@ -94,6 +94,7 @@ module MilkTea
     end
     ResolvedAttributeApplication = Data.define(:binding, :argument_values)
     AttributePresenceKey = Data.define(:target, :attribute_module_name, :attribute_name)
+    CallableResolution = Data.define(:kind, :value, :receiver)
     TypeParamConstraintBinding = Data.define(:interfaces) do
       def initialize(interfaces: []) = super
     end
@@ -185,30 +186,47 @@ module MilkTea
       end
 
       def check
-        install_builtin_types
-        install_builtin_attributes
-        install_imports
-        install_prelude_types
-        declare_named_types
-        resolve_generic_type_param_constraints
-        resolve_type_aliases
-        declare_attributes
-        resolve_aggregate_fields
-        resolve_enum_members
-        resolve_variant_arms
-        collect_emit_declarations
-        declare_top_level_values
-        check_attribute_applications
-        declare_functions
-        check_interface_conformances
-        check_top_level_values
-        finalize_top_level_const_values
-        check_top_level_static_asserts
-        check_functions
+        @completed_phases = Set.new
+
+        run_phase(:install_builtin_types)
+        run_phase(:install_builtin_attributes)
+        run_phase(:install_imports)
+        run_phase(:install_prelude_types, requires: [:install_imports])
+        run_phase(:declare_named_types, requires: [:install_builtin_types, :install_imports, :install_prelude_types])
+        run_phase(:resolve_generic_type_param_constraints, requires: [:declare_named_types])
+        run_phase(:resolve_type_aliases, requires: [:declare_named_types])
+        run_phase(:declare_attributes)
+        run_phase(:resolve_aggregate_fields, requires: [:resolve_type_aliases, :declare_named_types])
+        run_phase(:resolve_enum_members, requires: [:declare_named_types])
+        run_phase(:resolve_variant_arms, requires: [:declare_named_types])
+        run_phase(:collect_emit_declarations)
+        run_phase(:declare_top_level_values, requires: [:resolve_aggregate_fields, :resolve_type_aliases])
+        run_phase(:check_attribute_applications, requires: [:declare_attributes])
+        run_phase(:declare_functions, requires: [:resolve_aggregate_fields, :resolve_enum_members, :resolve_variant_arms])
+        run_phase(:check_interface_conformances, requires: [:declare_functions, :resolve_aggregate_fields])
+        run_phase(:check_top_level_values, requires: [:declare_top_level_values])
+        run_phase(:finalize_top_level_const_values, requires: [:check_top_level_values])
+        run_phase(:check_top_level_static_asserts, requires: [:finalize_top_level_const_values])
+        run_phase(:check_functions, requires: [:declare_functions, :resolve_aggregate_fields, :check_interface_conformances])
 
         build_analysis
       end
 
+      def run_phase(name, requires: [])
+        requires.each do |required|
+          unless @completed_phases&.include?(required)
+            raise "BUG: phase #{required} must run before #{name} — check phase ordering"
+          end
+        end
+        send(name)
+      ensure
+        @completed_phases << name if @completed_phases
+      end
+
+      def run_collecting_phase(name, requires: [])
+        catch_structural { run_phase(name, requires:) }
+      end
+
       def collect_emit_declarations
         collect_emit_from_declarations(expanded_declarations)
         @ctx.ast.declarations.grep(AST::ConstDecl).each { |decl| @ctx.const_declarations[decl.name] ||= decl }
@@ -274,23 +292,24 @@ module MilkTea
       def check_collecting_errors
         @collecting_errors = true
         @structural_errors = []
-
-        catch_structural { install_builtin_types }
-        catch_structural { install_builtin_attributes }
-        catch_structural { install_imports }
-        catch_structural { install_prelude_types }
-        catch_structural { declare_named_types }
-        catch_structural { resolve_generic_type_param_constraints }
-        catch_structural { resolve_type_aliases }
-        catch_structural { declare_attributes }
-        catch_structural { resolve_aggregate_fields }
-        catch_structural { resolve_enum_members }
-        catch_structural { resolve_variant_arms }
-        catch_structural { collect_emit_declarations }
-        catch_structural { declare_top_level_values }
-        catch_structural { check_attribute_applications }
-        catch_structural { declare_functions }
-        catch_structural { check_interface_conformances }
+        @completed_phases = Set.new
+
+        run_collecting_phase(:install_builtin_types)
+        run_collecting_phase(:install_builtin_attributes)
+        run_collecting_phase(:install_imports)
+        run_collecting_phase(:install_prelude_types, requires: [:install_imports])
+        run_collecting_phase(:declare_named_types, requires: [:install_builtin_types, :install_imports, :install_prelude_types])
+        run_collecting_phase(:resolve_generic_type_param_constraints, requires: [:declare_named_types])
+        run_collecting_phase(:resolve_type_aliases, requires: [:declare_named_types])
+        run_collecting_phase(:declare_attributes)
+        run_collecting_phase(:resolve_aggregate_fields, requires: [:resolve_type_aliases, :declare_named_types])
+        run_collecting_phase(:resolve_enum_members, requires: [:declare_named_types])
+        run_collecting_phase(:resolve_variant_arms, requires: [:declare_named_types])
+        run_collecting_phase(:collect_emit_declarations)
+        run_collecting_phase(:declare_top_level_values, requires: [:resolve_aggregate_fields, :resolve_type_aliases])
+        run_collecting_phase(:check_attribute_applications, requires: [:declare_attributes])
+        run_collecting_phase(:declare_functions, requires: [:resolve_aggregate_fields, :resolve_enum_members, :resolve_variant_arms])
+        run_collecting_phase(:check_interface_conformances, requires: [:declare_functions, :resolve_aggregate_fields])
 
         errors = @structural_errors.dup