mt-lang 0.3.17 → 0.3.22

data/lib/milk_tea/core/module_loader.rb

@@ -154,15 +154,37 @@ module MilkTea
       check_program(path).root_analysis
     end
 
-    def check_program(path)
+    def with_check_context(path, &block)
       Types::Registry.reset!
       requested_path = File.expand_path(path)
       previous_platform = @platform
       @platform ||= self.class.platform_suffix_for_path(requested_path)
       root_path = self.class.resolve_source_path(requested_path, platform: @platform, error_class: ModuleLoadError)
+      block.call(root_path)
+    ensure
+      @platform = previous_platform
+    end
+
+    def check_program(path)
+      with_check_context(path) do |root_path|
+        check_program_parallel(root_path)
+        build_program(root_path)
+      end
+    end
 
-      check_program_parallel(root_path)
+    # Variant of #check_program that collects errors instead of raising so
+    # diagnostic paths (check, debug, LSP) can report all issues at once.
+    # Returns { root_analysis: Analysis|nil, errors: [SemanticError], module_name: String|nil }.
+    def check_program_collecting(path)
+      with_check_context(path) do |root_path|
+        errors = []
+        check_program_parallel(root_path, collecting_errors: errors)
+        root_analysis = @analysis_cache[root_path]
+        { root_analysis: root_analysis, errors: errors, module_name: root_analysis&.module_name }
+      end
+    end
 
+    def build_program(root_path)
       root_analysis = @analysis_cache.fetch(root_path)
       analyses_by_module_name = @analysis_cache.each_value.each_with_object({}) do |analysis, modules|
         next unless analysis.module_name
@@ -176,11 +198,27 @@ module MilkTea
         analyses_by_path: @analysis_cache.dup.freeze,
         analyses_by_module_name: analyses_by_module_name.freeze,
       )
-    ensure
-      @platform = previous_platform
     end
 
-    def check_program_parallel(root_path)
+    def node_in_cycle?(node, graph)
+      # Start from each immediate successor to avoid the trivial self-path
+      successors = graph[node] || []
+      successors.each do |next_node|
+        next unless graph.key?(next_node)
+        return true if dfs_reachable_from(next_node, node, graph, {})
+      end
+      false
+    end
+
+    def dfs_reachable_from(current, target, graph, visited)
+      return false if visited[current]
+      return true if current == target
+
+      visited[current] = true
+      (graph[current] || []).any? { |neighbor| dfs_reachable_from(neighbor, target, graph, visited) }
+    end
+
+    def check_program_parallel(root_path, collecting_errors: nil)
       # Phase 1: Parse all transitive modules (sequential)
       parse_all(root_path)
 
@@ -194,12 +232,24 @@ module MilkTea
         graph[resolved_path] = deps
       end
 
-      # Phase 3: Topological sort into independent levels
+      # Phase 3: Topological sort into independent levels.
+      # Nodes that cannot be sorted are candidates for cycle membership,
+      # but not all of them are actually part of a cycle — some are just
+      # dependencies downstream from the cycle. We separate true cycle
+      # members (nodes reachable from themselves) from tail nodes.
       levels = topo_sort_levels(graph)
 
-      # Pre-register forward bindings for cycle members
       all_checked = levels.flatten.to_set
-      cycle_members = graph.keys.reject { |p| all_checked.include?(p) }
+      unsorted = graph.keys.reject { |p| all_checked.include?(p) }
+
+      # Among unsorted nodes, identify true cycle members: nodes that can
+      # reach themselves through the graph (belong to a strongly connected
+      # component of size > 1). Tail nodes that only depend on cycle members
+      # but have no path back to themselves are NOT cycle members.
+      cycle_members = unsorted.select { |node| node_in_cycle?(node, graph) }
+      tail_members = unsorted - cycle_members
+
+      # Pre-register forward bindings only for true cycle members
       cycle_members.each do |resolved_path|
         ast = @parse_cache[resolved_path]
         @forward_bindings[resolved_path] = create_forward_binding(ast)
@@ -209,10 +259,14 @@ module MilkTea
       # Pass 1: Check with forward bindings — registers type declarations.
       # SemanticError is expected (forward types lack fields/constructors)
       # but ModuleLoadError indicates a broken dependency graph.
+      # Do NOT collect Pass 1 errors — they are temporary failures caused
+      # by incomplete forward bindings that Pass 2 resolves.
       cycle_members.each do |resolved_path|
         check_path(resolved_path)
       rescue SemanticError
-        # Forward types can't satisfy constructors. Pass 2 will retry.
+        # Forward types can't satisfy constructors / functions / methods.
+        # Re-check in collecting mode to capture the analysis for population.
+        capture_analysis_for_cycle_member(resolved_path)
       end
 
       # Update forward type objects in-place with field/arm info from the
@@ -236,26 +290,45 @@ module MilkTea
           if real_type.respond_to?(:arms) && fw_type.respond_to?(:define_arms)
             fw_type.define_arms(real_type.arms) unless real_type.arms.empty?
           end
+          if real_type.respond_to?(:members) && fw_type.respond_to?(:define_members)
+            member_names = real_type.members
+            unless member_names.empty?
+              fw_type.define_members(real_type.backing_type, member_names)
+              values = member_names.each_with_object({}) { |n, h| h[n] = real_type.member_value(n) }
+              fw_type.define_member_values(values)
+            end
+          end
         end
       end
 
-      # Pass 2: Re-check with populated types — now cycle members see
-      # complete type information for each other.
+      # Replace forward bindings with fully populated bindings so that
+      # Pass 2 import resolution sees functions, methods, values, and
+      # interfaces — not just type skeletons.
+      populate_full_forward_bindings(cycle_members)
+
+      # Pass 2: Re-check with populated bindings — now cycle members see
+      # complete module information for each other.
       cycle_members.each do |resolved_path|
         previous = @analysis_cache.delete(resolved_path)
         check_path(resolved_path)
-      rescue SemanticError
+      rescue SemanticError => e
         @analysis_cache[resolved_path] = previous if previous
+        collecting_errors << e if collecting_errors
       end
       @forward_bindings.clear
 
-      # Phase 5: Check acyclic modules (they see fully-checked analyses for all imports)
-      levels.each do |level_paths|
+      # Phase 5: Check acyclic modules (they see fully-checked analyses for all imports).
+      # Also check tail members — nodes that were in the unsorted set but
+      # are not themselves part of a cycle; they just depended on cycle members.
+      (levels + [tail_members]).each do |level_paths|
         if level_paths.length == 1
           check_path(level_paths.first)
-        else
+        elsif level_paths.any?
           check_level_parallel(level_paths)
         end
+      rescue SemanticError => e
+        raise unless collecting_errors
+        collecting_errors << e
       end
     end
 
@@ -317,22 +390,62 @@ module MilkTea
     end
 
     def imported_modules_for_ast(ast, importer_path: nil)
+      resolve_imports_for_ast(ast, importer_path:, collecting: false)
+    end
+
+    def imported_modules_for_ast_collecting_errors(ast, importer_path: nil)
+      resolve_imports_for_ast(ast, importer_path:, collecting: true)
+    end
+
+    def resolve_imports_for_ast(ast, importer_path:, collecting: false)
       modules = {}
+      errors = []
+
+      if @import_resolve_depth
+        @import_resolve_depth += 1
+        if @import_resolve_depth > 80
+          raise SemanticError.new("import resolution depth exceeded")
+        end
+      else
+        @import_resolve_depth = 1
+      end
 
       ast.imports.each do |import|
-        import_path = @path_resolver.resolve_module_path(import.path.to_s, importer_path:, importer_module_name: ast.module_name.to_s)
+        begin
+          import_path = @path_resolver.resolve_module_path(import.path.to_s, importer_path:, importer_module_name: ast.module_name.to_s)
 
-        if @forward_bindings.key?(import_path)
-          modules[import.path.to_s] = @forward_bindings[import_path]
-        else
-          import_analysis = check_path(import_path)
-          modules[import.path.to_s] = @binder.module_binding(import_analysis)
+          if @forward_bindings.key?(import_path)
+            modules[import.path.to_s] = @forward_bindings[import_path]
+          else
+            import_analysis = collecting ? check_path_collecting_errors(import_path) : check_path(import_path)
+            modules[import.path.to_s] = @binder.module_binding(import_analysis)
+          end
+        rescue ModuleLoadError, PackageLockError, SemanticError => e
+          raise unless collecting
+
+          handle_circular_import_in_collecting_mode(import, import_path, modules, errors, e)
         end
       end
 
-      @async_runtime_installer.install_async_runtime_dependency!(ast, modules, importer_path:, collecting_errors: false)
-      @prelude_installer.install_prelude_modules!(ast, modules, importer_path:, collecting_errors: false)
+      begin
+        @async_runtime_installer.install_async_runtime_dependency!(ast, modules, importer_path:, collecting_errors: collecting)
+      rescue ModuleLoadError, PackageLockError => e
+        raise unless collecting
+        errors << ImportResolutionError.new(import: nil, error: e)
+      end
+
+      begin
+        @prelude_installer.install_prelude_modules!(ast, modules, importer_path:, collecting_errors: collecting)
+      rescue ModuleLoadError, PackageLockError => e
+        raise unless collecting
+        errors << ImportResolutionError.new(import: nil, error: e)
+      end
+
+      return ImportResolution.new(modules: modules.freeze, errors: errors.freeze) if collecting
+
       modules.freeze
+    ensure
+      @import_resolve_depth -= 1 if @import_resolve_depth
     end
 
     def build_global_import_index(ast)
@@ -358,40 +471,6 @@ module MilkTea
       index
     end
 
-    def imported_modules_for_ast_collecting_errors(ast, importer_path: nil)
-      modules = {}
-      errors = []
-
-      ast.imports.each do |import|
-        begin
-          import_path = @path_resolver.resolve_module_path(import.path.to_s, importer_path:, importer_module_name: ast.module_name.to_s)
-
-          if @forward_bindings.key?(import_path)
-            modules[import.path.to_s] = @forward_bindings[import_path]
-          else
-            import_analysis = check_path_collecting_errors(import_path)
-            modules[import.path.to_s] = @binder.module_binding(import_analysis)
-          end
-        rescue ModuleLoadError, PackageLockError, SemanticError => e
-          errors << ImportResolutionError.new(import:, error: e)
-        end
-      end
-
-      begin
-        @async_runtime_installer.install_async_runtime_dependency!(ast, modules, importer_path:, collecting_errors: true)
-      rescue ModuleLoadError, PackageLockError => e
-        errors << ImportResolutionError.new(import: nil, error: e)
-      end
-
-      begin
-        @prelude_installer.install_prelude_modules!(ast, modules, importer_path:, collecting_errors: true)
-      rescue ModuleLoadError, PackageLockError => e
-        errors << ImportResolutionError.new(import: nil, error: e)
-      end
-
-      ImportResolution.new(modules: modules.freeze, errors: errors.freeze)
-    end
-
     # Errors collected per analyzed import path during collecting-mode checks.
     # Populated by #check_path_collecting_errors; used by the CLI `check` command
     # to surface errors in a single file's imported modules (otherwise only
@@ -527,6 +606,74 @@ module MilkTea
       normalized_path == normalized_root || normalized_path.start_with?(normalized_root + File::SEPARATOR)
     end
 
+    def handle_circular_import_in_collecting_mode(import, import_path, modules, errors, error)
+      # When a circular import is detected in collecting mode, create a
+      # forward binding for the target module so the importing module can
+      # at minimum resolve type references. Without this the import is
+      # entirely absent, which causes downstream crashes in module_binding.
+      if import_path && error.is_a?(ModuleLoadError) && error.message.start_with?("circular import")
+        circular_ast = @parse_cache[import_path] || load_file(import_path)
+        if circular_ast
+          @forward_bindings[import_path] ||= create_forward_binding(circular_ast)
+          modules[import.path.to_s] = @forward_bindings[import_path]
+        end
+      end
+
+      errors << ImportResolutionError.new(import:, error:)
+    end
+
+    def capture_analysis_for_cycle_member(resolved_path)
+      return if @analysis_cache[resolved_path]
+
+      ast = @parse_cache[resolved_path]
+      return unless ast
+
+      @checking_paths << resolved_path
+      import_result = resolve_imports_for_ast(ast, importer_path: resolved_path, collecting: true)
+      result = SemanticAnalyzer.check_collecting_errors(ast, imported_modules: import_result.modules, path: resolved_path)
+      @analysis_cache[resolved_path] = result[:analysis] if result[:analysis]
+    rescue StandardError
+      # Analysis capture is best-effort.
+    ensure
+      @checking_paths.pop
+    end
+
+    def populate_full_forward_bindings(cycle_members)
+      cycle_members.each do |resolved_path|
+        analysis = @analysis_cache[resolved_path]
+        next unless analysis
+
+        fw_binding = @forward_bindings[resolved_path]
+        next unless fw_binding
+
+        full_binding = @binder.module_binding(analysis)
+        merged_types = fw_binding.types.merge(
+          full_binding.types.reject { |name, _| fw_binding.types.key?(name) }
+        )
+
+        @forward_bindings[resolved_path] = ModuleBinding.new(
+          name: full_binding.name,
+          types: merged_types,
+          type_declarations: full_binding.type_declarations,
+          interfaces: full_binding.interfaces,
+          attributes: full_binding.attributes,
+          attribute_applications: full_binding.attribute_applications,
+          values: full_binding.values,
+          functions: full_binding.functions,
+          methods: full_binding.methods,
+          implemented_interfaces: full_binding.implemented_interfaces,
+          imports: full_binding.imports,
+          private_types: full_binding.private_types,
+          private_interfaces: full_binding.private_interfaces,
+          private_attributes: full_binding.private_attributes,
+          private_values: full_binding.private_values,
+          private_functions: full_binding.private_functions,
+          private_methods: full_binding.private_methods,
+          private_implemented_interfaces: full_binding.private_implemented_interfaces,
+        )
+      end
+    end
+
     def create_forward_binding(ast)
       module_name = ast.module_name.to_s
       types = {}
@@ -534,15 +681,21 @@ module MilkTea
       ast.declarations.each do |decl|
         case decl
         when AST::StructDecl
-          types[decl.name] = Types::Struct.new(decl.name, module_name:)
+          types[decl.name] = decl.type_params.empty? ?
+            Types::Struct.new(decl.name, module_name:) :
+            Types::GenericStructDefinition.new(decl.name, decl.type_params.map(&:name))
         when AST::VariantDecl
-          types[decl.name] = Types::Variant.new(decl.name, module_name:)
+          types[decl.name] = decl.type_params.empty? ?
+            Types::Variant.new(decl.name, module_name:) :
+            Types::GenericVariantDefinition.new(decl.name, decl.type_params.map(&:name))
         when AST::EnumDecl
           types[decl.name] = Types::Enum.new(decl.name, module_name:)
         when AST::FlagsDecl
           types[decl.name] = Types::Flags.new(decl.name, module_name:)
         when AST::OpaqueDecl
           types[decl.name] = Types::Opaque.new(decl.name, module_name:, external: false)
+        when AST::UnionDecl
+          types[decl.name] = Types::Union.new(decl.name, module_name:)
         end
       end
 

data/lib/milk_tea/core/module_path_resolver.rb

@@ -16,19 +16,23 @@ module MilkTea
 
       relative_path = File.join(*module_name.split(".")) + ".mt"
       blocked = false
-      candidate = @module_roots.lazy.map { |root| ModuleLoader.resolve_source_path(File.join(root, relative_path), platform: @platform) }.find do |path|
-        next false unless source_path_available?(path)
+      candidate = nil
+      @module_roots.each do |root|
+        path = ModuleLoader.resolve_source_path(File.join(root, relative_path), platform: @platform)
+        next unless source_path_available?(path)
 
         allowed = import_allowed?(module_name, importer_path, path)
         blocked ||= !allowed
-        allowed
+        if allowed
+          candidate = path
+          break
+        end
       end
       raise ModuleLoadError.new("package dependency not declared", path: module_name) if blocked
       unless candidate
         message = namespace_hint_for_missing_module(module_name, importer_path:, importer_module_name:) || "module not found"
         raise ModuleLoadError.new(message, path: module_name)
       end
-
       File.expand_path(candidate)
     end
 
@@ -119,9 +123,6 @@ module MilkTea
       return @package_manifest_cache[manifest_path] if @package_manifest_cache.key?(manifest_path)
 
       @package_manifest_cache[manifest_path] = PackageManifest.load(path)
-    rescue PackageManifestError
-      @package_manifest_cache[manifest_path] = nil if manifest_path
-      nil
     end
 
     def package_namespace_match?(module_name, package_name)

data/lib/milk_tea/core/parser/declarations.rb

@@ -18,6 +18,39 @@ module MilkTea
         AST::Import.new(path:, alias_name:, line:, column: local_column, length: local_name.length)
       end
 
+      DECL_KIND = {
+        var:        { method: :parse_var_decl,        reject_attrs: "var" },
+        type:       { method: :parse_type_alias_decl, reject_attrs: "type" },
+        union:      { method: :parse_union_decl },
+        enum:       { method: :parse_enum_decl,       enum_class: AST::EnumDecl },
+        flags:      { method: :parse_enum_decl,       enum_class: AST::FlagsDecl },
+        opaque:     { method: :parse_opaque_decl,     reject_attrs: "opaque" },
+        interface:  { method: :parse_interface_decl,  reject_attrs: "interface" },
+        event:      { method: :parse_event_decl },
+        attribute:  { method: :parse_attribute_decl,  reject_attrs: "attribute" },
+      }.freeze
+
+      def dispatch_decl_kind(kind, visibility:, attributes:)
+        info = DECL_KIND.fetch(kind)
+        reject_attributes!(attributes, info[:reject_attrs]) if info[:reject_attrs]
+
+        if info[:enum_class]
+          send(info[:method], info[:enum_class], visibility:, attributes:)
+        elsif info[:reject_attrs]
+          send(info[:method], visibility:)
+        else
+          send(info[:method], visibility:, attributes:)
+        end
+      end
+
+      def parse_const_or_function_decl(visibility:, attributes:)
+        if match(:function)
+          parse_function_def(visibility:, const: true, attributes:)
+        else
+          parse_const_decl(visibility:, attributes:)
+        end
+      end
+
       def parse_declaration
         attributes = parse_attribute_applications
         visibility, visibility_token = parse_visibility
@@ -25,38 +58,29 @@ module MilkTea
         if builtin_attribute_identifier?(peek)
           raise error(peek, "layout modifiers must use attributes like @[packed] or @[align(...)]")
         elsif match(:attribute)
-          reject_attributes!(attributes, "attribute")
-          parse_attribute_decl(visibility:)
+          dispatch_decl_kind(:attribute, visibility:, attributes:)
         elsif match(:const)
-          if match(:function)
-            parse_function_def(visibility:, const: true, attributes:)
-          else
-            parse_const_decl(visibility:, attributes:)
-          end
+          parse_const_or_function_decl(visibility:, attributes:)
         elsif match(:var)
-          reject_attributes!(attributes, "var")
-          parse_var_decl(visibility:)
+          dispatch_decl_kind(:var, visibility:, attributes:)
         elsif match(:event)
-          parse_event_decl(visibility:, attributes:)
+          dispatch_decl_kind(:event, visibility:, attributes:)
         elsif match(:type)
-          reject_attributes!(attributes, "type")
-          parse_type_alias_decl(visibility:)
+          dispatch_decl_kind(:type, visibility:, attributes:)
         elsif match(:struct)
           parse_struct_decl(visibility:, attributes:)
         elsif match(:union)
-          parse_union_decl(visibility:, attributes:)
+          dispatch_decl_kind(:union, visibility:, attributes:)
         elsif match(:enum)
-          parse_enum_decl(AST::EnumDecl, visibility:, attributes:)
+          dispatch_decl_kind(:enum, visibility:, attributes:)
         elsif match(:flags)
-          parse_enum_decl(AST::FlagsDecl, visibility:, attributes:)
+          dispatch_decl_kind(:flags, visibility:, attributes:)
         elsif match(:variant)
           parse_variant_decl(visibility:, attributes:)
         elsif match(:interface)
-          reject_attributes!(attributes, "interface")
-          parse_interface_decl(visibility:)
+          dispatch_decl_kind(:interface, visibility:, attributes:)
         elsif match(:opaque)
-          reject_attributes!(attributes, "opaque")
-          parse_opaque_decl(visibility:)
+          dispatch_decl_kind(:opaque, visibility:, attributes:)
         elsif match(:extending)
           reject_attributes!(attributes, "extending")
           raise error(visibility_token, "public is not allowed on extending blocks") if visibility == :public

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

@@ -35,14 +35,14 @@ module MilkTea
           consume(:newline, "expected newline after 'if condition:' in if expression")
           consume(:indent, "expected indented body in if expression")
           then_expression = parse_expression
-          consume_end_of_statement unless block_expression?(then_expression)
+          finish_expression_statement(then_expression)
           consume(:dedent, "expected end of if expression body")
           consume(:else, "expected 'else' in if expression")
           consume(:colon, "expected ':' after 'else' in if expression")
           consume(:newline, "expected newline after 'else:' in if expression")
           consume(:indent, "expected indented else body in if expression")
           else_expression = parse_expression
-          consume_end_of_statement unless block_expression?(else_expression)
+          finish_expression_statement(else_expression)
           consume(:dedent, "expected end of else expression body")
         end
 
@@ -97,7 +97,7 @@ module MilkTea
                        end
         consume(:colon, "expected ':' after match expression arm pattern")
         value = parse_expression
-        consume_end_of_statement unless block_expression?(value)
+        finish_expression_statement(value)
         patterns.map do |pattern|
           AST::MatchExprArm.new(
             pattern:,
@@ -549,10 +549,7 @@ module MilkTea
         end
 
         parser = self.class.new(tokens, path: @path)
-        parser.instance_variable_set(:@known_type_names, @known_type_names.dup)
-        parser.instance_variable_set(:@known_import_aliases, @known_import_aliases.dup)
-        parser.instance_variable_set(:@known_generic_callable_names, @known_generic_callable_names.dup)
-        parser.instance_variable_set(:@current_type_param_names, @current_type_param_names.dup)
+        parser.apply_parser_context(parser_context)
 
         expression = parser.parse_expression
         parser.skip_newlines
@@ -643,7 +640,7 @@ module MilkTea
 
       def definite_type_argument?(value)
         case value
-        when AST::FunctionType
+        when AST::FunctionType, AST::TupleType
           true
         when AST::TypeRef
           known_type_like_name?(value.name.parts.first)

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

@@ -147,7 +147,7 @@ module MilkTea
 
             else_body = parse_block
           else
-            consume_end_of_statement unless block_expression?(value)
+            finish_expression_statement(value)
           end
         else
           raise error(name_token, "local declaration without initializer requires a type") unless var_type
@@ -366,7 +366,7 @@ module MilkTea
         if match_arm_expr_form?
           consume(:colon, "expected ':' after match expression arm pattern")
           value = parse_expression
-          consume_end_of_statement unless block_expression?(value)
+          finish_expression_statement(value)
           patterns.map do |pattern|
             AST::MatchExprArm.new(
               pattern:,
@@ -585,7 +585,7 @@ module MilkTea
         token = previous
         line = token.line
         value = check(:newline) ? nil : parse_expression
-        consume_end_of_statement unless block_expression?(value)
+        finish_expression_statement(value)
         AST::ReturnStmt.new(value:, line:, column: token.column, length: token.lexeme.length)
       end
 
@@ -768,10 +768,10 @@ module MilkTea
           operator = previous.lexeme
           column = previous.column
           value = parse_expression
-          consume_end_of_statement unless block_expression?(value)
+          finish_expression_statement(value)
           AST::Assignment.new(target: expression, operator:, value:, line:, column:)
         else
-          consume_end_of_statement unless block_expression?(expression)
+          finish_expression_statement(expression)
           AST::ExpressionStmt.new(expression:, line:)
         end
       end

data/lib/milk_tea/core/parser.rb

@@ -38,6 +38,8 @@ module MilkTea
       def initialize(ast:, errors: []) = super
     end
 
+    ParseContext = Data.define(:known_type_names, :known_import_aliases, :known_generic_callable_names, :current_type_param_names)
+
     include Parse::Blocks
     include Parse::Recovery
     include Parse::Types
@@ -250,6 +252,10 @@ module MilkTea
       consume(:newline, "expected end of statement")
     end
 
+    def finish_expression_statement(value)
+      consume_end_of_statement unless block_expression?(value)
+    end
+
     def block_expression?(expression)
       expression.is_a?(AST::ProcExpr) || expression.is_a?(AST::MatchExpr) || expression.is_a?(AST::IfExpr)
     end
@@ -304,6 +310,26 @@ module MilkTea
       @current_type_param_names = saved_names
     end
 
+    # Returns a ParseContext snapshot of the parser state that must propagate
+    # to nested parsers (e.g. format string interpolations).  When adding
+    # parser state that must be cloned, update both this method,
+    # apply_parser_context, and the ParseContext Data class.
+    def parser_context
+      ParseContext.new(
+        known_type_names: @known_type_names.dup,
+        known_import_aliases: @known_import_aliases.dup,
+        known_generic_callable_names: @known_generic_callable_names.dup,
+        current_type_param_names: @current_type_param_names.dup,
+      )
+    end
+
+    def apply_parser_context(context)
+      @known_type_names = context.known_type_names
+      @known_import_aliases = context.known_import_aliases
+      @known_generic_callable_names = context.known_generic_callable_names
+      @current_type_param_names = context.current_type_param_names
+    end
+
     def seed_known_names
       MilkTea::BUILTIN_TYPE_NAMES.each { |name| @known_type_names[name] = true }