Merge pull request #1149 from block/myron/steep-2.0.0

myronmarston · web-flow · commit 3d5b66567940 · 2026-04-27T14:56:02.000Z
Upgrade steep/RBS to 2.0/4.0.

Steep 2.0 + RBS 4.0 are stricter about: void in union types, duplicated method definitions across RBS files, missing interface method implementations.

Most of these changes make our types more accurate.
diff --git a/AGENTS.md b/AGENTS.md
@@ -168,6 +168,14 @@ Custom gems can be added via `Gemfile-custom` (see `Gemfile-custom.example`), th
 ### RBS Type Signatures
 
 - When defining RBS signatures for extension modules, prefer declaring the concrete type a module extends rather than defining custom interfaces. For example, use `module IndexExtension : ::ElasticGraph::SchemaDefinition::Indexing::Index` instead of creating a custom `_IndexExtensionInterface`.
+- Place interface methods on the narrowest correct interface. If a method only exists on indexable types, put it on `_IndexableType`, not `_Type`.
+- Define `type` aliases (e.g. `type abstractType = InterfaceType | UnionType`) for repeated union types rather than duplicating them across signatures.
+- When Steep can't infer a narrowed type from an expression, prefer an inline RBS type annotation comment (e.g. `# : SchemaElements::InterfaceType`) over a `_ =` cast. Use `_ =` only as a last resort when an annotation won't work.
+- For `Data.define` blocks where Steep can't type-check the dynamically generated `initialize`, use `# @implements ClassName` with a corresponding `class ClassName < Data` in the RBS file that declares the method signatures. Avoid `__skip__ = def`.
+- Prefer `&:method_name` over explicit blocks. If Steep complains, add the missing method to the RBS rather than rewriting as `{ |x| x.method_name }`.
+- Keep `@ivar` declarations adjacent to their accessor method in the RBS, not grouped elsewhere.
+- Be precise about collection element types in RBS — e.g. if a `Set` only ever contains `UnionType`, type it as `Set[UnionType]` not `Set[UnionType | InterfaceType]`.
+- Use `@dynamic` annotations only for methods that actually exist at runtime (provided by delegation, Struct, or included modules). Never use `@dynamic` for methods that would raise `NoMethodError`.
 
 ### Testing
 
diff --git a/Gemfile b/Gemfile
@@ -40,7 +40,7 @@ group :development do
   gem "simplecov", "~> 0.22"
   gem "simplecov-console", "~> 0.9", ">= 0.9.5"
   gem "standard", "~> 1.54.0"
-  gem "steep", "~> 1.10.0", platforms: :ruby
+  gem "steep", "~> 2.0.0", platforms: :ruby
   gem "super_diff", "~> 0.18"
   gem "vcr", "~> 6.4"
 end
diff --git a/Gemfile.lock b/Gemfile.lock
@@ -455,7 +455,6 @@ GEM
     multi_json (1.20.1)
     multi_json (1.20.1-java)
       concurrent-ruby (~> 1.2)
-    mutex_m (0.3.0)
     net-http (0.9.1)
       uri (>= 0.11.1)
     nokogiri (1.19.2)
@@ -510,8 +509,9 @@ GEM
     rb-fsevent (0.11.2)
     rb-inotify (0.11.1)
       ffi (~> 1.0)
-    rbs (3.10.4)
+    rbs (4.0.2)
       logger
+      prism (>= 1.6.0)
       tsort
     rdoc (7.2.0)
       erb
@@ -613,19 +613,18 @@ GEM
     standard-performance (1.9.0)
       lint_roller (~> 1.1)
       rubocop-performance (~> 1.26.0)
-    steep (1.10.0)
-      activesupport (>= 5.1)
+    steep (2.0.0)
       concurrent-ruby (>= 1.1.10)
       csv (>= 3.0.9)
       fileutils (>= 1.1.0)
       json (>= 2.1.0)
       language_server-protocol (>= 3.17.0.4, < 4.0)
       listen (~> 3.0)
       logger (>= 1.3.0)
-      mutex_m (>= 0.3.0)
-      parser (>= 3.1)
+      parser (>= 3.2)
+      prism (>= 0.25.0)
       rainbow (>= 2.2.2, < 4.0)
-      rbs (~> 3.9)
+      rbs (~> 4.0)
       securerandom (>= 0.1)
       strscan (>= 1.0.0)
       terminal-table (>= 2, < 5)
@@ -733,7 +732,7 @@ DEPENDENCIES
   simplecov (~> 0.22)
   simplecov-console (~> 0.9, >= 0.9.5)
   standard (~> 1.54.0)
-  steep (~> 1.10.0)
+  steep (~> 2.0.0)
   super_diff (~> 0.18)
   vcr (~> 6.4)
   yard (~> 0.9, >= 0.9.43)
@@ -871,7 +870,6 @@ CHECKSUMS
   module_methods (0.1.0) sha256=71cabd8e5b8537316a2e4a543a778726f34fab048d6d5fe97f3766c7b4e406a1
   multi_json (1.20.1) sha256=2f3934e805cc45ef91b551a1f89d0e9191abd06a5e04a2ef09a6a036c452ca6d
   multi_json (1.20.1-java) sha256=db1b1e8a461ed0d024b30bfd462bab87e7ceedc967457ba3f791043fdf263b95
-  mutex_m (0.3.0) sha256=cfcb04ac16b69c4813777022fdceda24e9f798e48092a2b817eb4c0a782b0751
   net-http (0.9.1) sha256=25ba0b67c63e89df626ed8fac771d0ad24ad151a858af2cc8e6a716ca4336996
   nokogiri (1.19.2) sha256=38fdd8b59db3d5ea9e7dfb14702e882b9bf819198d5bf976f17ebce12c481756
   nokogiri (1.19.2-arm-linux-gnu) sha256=b7fa1139016f3dc850bda1260988f0d749934a939d04ef2da13bec060d7d5081
@@ -900,7 +898,7 @@ CHECKSUMS
   rake (13.4.2) sha256=cb825b2bd5f1f8e91ca37bddb4b9aaf345551b4731da62949be002fa89283701
   rb-fsevent (0.11.2) sha256=43900b972e7301d6570f64b850a5aa67833ee7d87b458ee92805d56b7318aefe
   rb-inotify (0.11.1) sha256=a0a700441239b0ff18eb65e3866236cd78613d6b9f78fea1f9ac47a85e47be6e
-  rbs (3.10.4) sha256=b17d7c4be4bb31a11a3b529830f0aa206a807ca42f2e7921a3027dfc6b7e5ce8
+  rbs (4.0.2) sha256=af75671e66cd03434cc546622741ebf83f6197ec4328375805306330bf78ef25
   rdoc (7.2.0) sha256=8650f76cd4009c3b54955eb5d7e3a075c60a57276766ebf36f9085e8c9f23192
   redcarpet (3.6.1) sha256=d444910e6aa55480c6bcdc0cdb057626e8a32c054c29e793fa642ba2f155f445
   regexp_parser (2.12.0) sha256=35a916a1d63190ab5c9009457136ae5f3c0c7512d60291d0d1378ba18ce08ebb
@@ -942,7 +940,7 @@ CHECKSUMS
   standard (1.54.0) sha256=7a4b08f83d9893083c8f03bc486f0feeb6a84d48233b40829c03ef4767ea0100
   standard-custom (1.0.2) sha256=424adc84179a074f1a2a309bb9cf7cd6bfdb2b6541f20c6bf9436c0ba22a652b
   standard-performance (1.9.0) sha256=49483d31be448292951d80e5e67cdcb576c2502103c7b40aec6f1b6e9c88e3f2
-  steep (1.10.0) sha256=1b295b55f9aaff1b8d3ee42453ee55bc2a1078fda0268f288edb2dc014f4d7d1
+  steep (2.0.0) sha256=6eb0ecc09637bbb54f0a5f2cf63daea6d3208ccace64b4f1107d976333605c30
   stringio (3.2.0) sha256=c37cb2e58b4ffbd33fe5cd948c05934af997b36e0b6ca6fdf43afa234cf222e1
   strscan (3.1.8) sha256=aae2db611a225559f21ffbb71765c9a4e60fd262534a9ea84f4f11c7f32f679e
   strscan (3.1.8-java) sha256=07c9fb169931fc7327e9ae64b27999e355c2eadd0eaae4ed0f1e7d4e05a2b429
diff --git a/elasticgraph-apollo/lib/elastic_graph/apollo/schema_definition/api_extension.rb b/elasticgraph-apollo/lib/elastic_graph/apollo/schema_definition/api_extension.rb
@@ -345,7 +345,7 @@ def define_apollo_schema_elements
           state.after_user_definition_complete do
             # Add @key directives to all root document types with an id field.
             state.object_types_by_name.values
-              .grep(ElasticGraph::SchemaDefinition::SchemaElements::ObjectType)
+              .grep(ElasticGraph::SchemaDefinition::SchemaElements::ObjectType) # : ::Array[::ElasticGraph::SchemaDefinition::SchemaElements::ObjectType & ObjectTypeExtension]
               .select { |object_type| object_type.root_document_type? && object_type.graphql_fields_by_name.key?("id") }
               .each { |object_type| object_type.apollo_key fields: "id" }
 
diff --git a/elasticgraph-datastore_core/sig/elastic_graph/datastore_core/index_definition.rbs b/elasticgraph-datastore_core/sig/elastic_graph/datastore_core/index_definition.rbs
@@ -8,7 +8,7 @@ module ElasticGraph
       def has_custom_routing?: () -> bool
       def max_result_window: () -> ::Integer
       def searches_could_hit_incomplete_docs?: () -> bool
-      def cluster_to_query: () -> ::String
+      def cluster_to_query: () -> ::String?
       def clusters_to_index_into: () -> ::Array[::String]
       def ignored_values_for_routing: () -> ::Set[::String]
       def all_accessible_cluster_names: () -> ::Array[::String]
diff --git a/elasticgraph-health_check/lib/elastic_graph/health_check/health_checker.rb b/elasticgraph-health_check/lib/elastic_graph/health_check/health_checker.rb
@@ -225,7 +225,7 @@ def validate_and_normalize_config(config)
       def all_known_clusters
         @all_known_clusters ||= @indexed_document_types_by_name.flat_map do |_, index_type|
           index_type.search_index_definitions.flat_map do |index_def|
-            [index_def.cluster_to_query] + index_def.clusters_to_index_into
+            [index_def.cluster_to_query].compact + index_def.clusters_to_index_into
           end
         end + @datastore_clients_by_name.keys
       end
diff --git a/elasticgraph-indexer/lib/elastic_graph/indexer/record_preparer.rb b/elasticgraph-indexer/lib/elastic_graph/indexer/record_preparer.rb
@@ -100,13 +100,13 @@ def initialize(indexing_preparer_by_scalar_type_name, type_metas)
       def prepare_for_index(type_name, value, mapping_properties)
         type_name = type_name.delete_suffix("!")
 
-        return nil if value.nil?
+        return (_ = nil) if value.nil? # Steep 2.0 narrows to nil here but can't see it satisfies T
 
         if (preparer = @indexing_preparer_by_scalar_type_name[type_name])
           return (_ = preparer).prepare_for_indexing(value)
         end
 
-        case value
+        _ = case value # Steep 2.0 can't narrow generic T through case/when branches
         when ::Array
           element_type_name = type_name.delete_prefix("[").delete_suffix("]")
           value.map { |v| prepare_for_index(element_type_name, v, mapping_properties) }
diff --git a/elasticgraph-indexer/sig/elastic_graph/indexer/record_preparer.rbs b/elasticgraph-indexer/sig/elastic_graph/indexer/record_preparer.rbs
@@ -1,7 +1,7 @@
 module ElasticGraph
   class Indexer
     interface _RecordPreparer
-      def prepare_for_index: [T] (::String, T, ::Hash[::String, untyped]) -> T
+      def prepare_for_index: [T < ::Object] (::String, T, ::Hash[::String, untyped]) -> T
     end
 
     class RecordPreparer
diff --git a/elasticgraph-local/sig/elastic_graph/local/rake_tasks.rbs b/elasticgraph-local/sig/elastic_graph/local/rake_tasks.rbs
@@ -33,6 +33,7 @@ module ElasticGraph
       def define_docker_tasks: (::String, ::String, ::Array[::String], ::Regexp) -> void
       def define_docker_tasks_for_version: (::String, ::Symbol, ::String, port: ::Integer, version: ::String, env: ::String, ready_log_line: ::Regexp) -> void
       def define_other_tasks: () -> void
+      def run_rackup: (::String) -> void
 
       @local_datastore_url: ::String?
       def local_datastore_url: () -> ::String
diff --git a/elasticgraph-schema_definition/lib/elastic_graph/schema_definition/indexing/json_schema_with_metadata.rb b/elasticgraph-schema_definition/lib/elastic_graph/schema_definition/indexing/json_schema_with_metadata.rb
@@ -158,7 +158,13 @@ def identify_missing_necessary_fields(json_schema, old_type_name_by_current_name
 
             @state.object_types_by_name.values
               .select { |type| type.has_own_index_def? && !@derived_indexing_type_names.include?(type.name) }
-              .flat_map { |object_type| identify_missing_necessary_fields_for_index_def(object_type, object_type.own_index_def, json_schema_resolver, version) }
+              .flat_map do |object_type|
+                identify_missing_necessary_fields_for_index_def(
+                  object_type,
+                  object_type.own_index_def, # : Indexing::Index
+                  json_schema_resolver, version
+                )
+              end
           end
 
           def identify_missing_necessary_fields_for_index_def(object_type, index_def, json_schema_resolver, json_schema_version)
diff --git a/elasticgraph-schema_definition/lib/elastic_graph/schema_definition/mixins/implements_interfaces.rb b/elasticgraph-schema_definition/lib/elastic_graph/schema_definition/mixins/implements_interfaces.rb
@@ -125,15 +125,15 @@ def to_sdl(&field_arg_selector)
         # @return [Set<UnionType, InterfaceType>] set of supertypes
         # @private
         def recursively_resolve_supertypes
-          union_memberships = schema_def_state.union_types_by_member_ref[type_ref]
+          union_memberships = schema_def_state.union_types_by_member_ref[type_ref] # : ::Set[abstractType]
           union_memberships | recursively_resolve_interface_supertypes
         end
 
         private
 
         def recursively_resolve_interface_supertypes(ancestors: Set.new)
           implemented_interfaces.flat_map do |interface_ref|
-            interface = interface_ref.resolved
+            interface = interface_ref.resolved # : SchemaElements::InterfaceType
 
             if ancestors.include?(interface)
               raise Errors::SchemaError, "Your schema has self-referential types, which are not allowed, since " \
diff --git a/elasticgraph-schema_definition/lib/elastic_graph/schema_definition/results.rb b/elasticgraph-schema_definition/lib/elastic_graph/schema_definition/results.rb
@@ -381,7 +381,7 @@ def verify_runtime_metadata(runtime_metadata)
             end
           end
 
-        unused_resolvers = registered_resolvers.except(*fields_by_resolvers.keys, *state.built_in_graphql_resolvers).keys
+        unused_resolvers = registered_resolvers.except(*fields_by_resolvers.keys, *state.built_in_graphql_resolvers.to_a).keys
 
         unless unused_resolvers.empty?
           state.output.puts <<~EOS
diff --git a/elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/object_type.rb b/elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/object_type.rb
@@ -30,7 +30,7 @@ class ObjectType < DelegateClass(TypeWithSubfields)
         include Mixins::SupportsFilteringAndAggregation
 
         # `include HasIndices` provides the following methods:
-        # @dynamic runtime_metadata, derived_indexed_types, indices, indexed?, abstract?
+        # @dynamic runtime_metadata, derived_indexed_types, indices, root_document_type?, abstract?, directly_queryable?
         include Mixins::HasIndices
 
         # `include ImplementsInterfaces` provides the following methods:
diff --git a/elasticgraph-schema_definition/sig/elastic_graph/schema_definition/api.rbs b/elasticgraph-schema_definition/sig/elastic_graph/schema_definition/api.rbs
@@ -17,14 +17,15 @@ module ElasticGraph
       include _NamedElement
       def type_ref: () -> SchemaElements::TypeReference
       def graphql_only?: () -> bool
-      def root_document_type?: () -> bool
       def to_sdl: () ?{ (SchemaElements::Field::argument) -> boolish } -> ::String
       def derived_graphql_types: () -> ::Array[SchemaElements::graphQLType]
       def to_indexing_field_type: () -> Indexing::_FieldType
     end
 
     interface _IndexableType
       include _Type
+      def root_document_type?: () -> bool
+      def directly_queryable?: () -> bool
       def abstract?: () -> bool
       def indices: () -> ::Array[Indexing::Index]
       def runtime_metadata: (::Array[SchemaArtifacts::RuntimeMetadata::UpdateTarget]) -> SchemaArtifacts::RuntimeMetadata::ObjectType
@@ -47,6 +48,8 @@ module ElasticGraph
     # We could list other mixins here but will do that as there is need over time.
     type indexableType = _IndexableType & Mixins::HasDirectives & Mixins::SupportsFilteringAndAggregation & Mixins::HasIndices
 
+    type abstractType = SchemaElements::InterfaceType | SchemaElements::UnionType
+
     class API
       attr_reader state: State
       attr_reader factory: Factory
diff --git a/elasticgraph-schema_definition/sig/elastic_graph/schema_definition/mixins/has_subtypes.rbs b/elasticgraph-schema_definition/sig/elastic_graph/schema_definition/mixins/has_subtypes.rbs
@@ -2,7 +2,7 @@ module ElasticGraph
   module SchemaDefinition
     module Mixins
       interface _AbstractType
-        include _Type
+        include _IndexableType
         def resolve_subtypes: () -> ::Array[SchemaElements::ObjectType]
         def schema_def_state: () -> State
       end
@@ -25,7 +25,7 @@ module ElasticGraph
           (SchemaElements::ObjectType) -> ::Hash[::String, SchemaElements::Field]
         } -> ::Hash[::String, SchemaElements::Field]
 
-        def subtypes_indexed?: () -> bool
+        def subtypes_are_root_document_types?: () -> bool
       end
     end
   end
diff --git a/elasticgraph-schema_definition/sig/elastic_graph/schema_definition/mixins/implements_interfaces.rbs b/elasticgraph-schema_definition/sig/elastic_graph/schema_definition/mixins/implements_interfaces.rbs
@@ -5,7 +5,11 @@ module ElasticGraph
         def implements: (*::String) -> void
         attr_reader implemented_interfaces: ::Array[SchemaElements::TypeReference]
         def verify_graphql_correctness!: () -> void
-        def recursively_resolve_supertypes: () -> ::Set[SchemaElements::UnionType | SchemaElements::InterfaceType]
+        def recursively_resolve_supertypes: () -> ::Set[abstractType]
+
+        private
+
+        def recursively_resolve_interface_supertypes: (?ancestors: ::Set[abstractType]) -> ::Array[abstractType]
       end
     end
   end
diff --git a/elasticgraph-schema_definition/sig/elastic_graph/schema_definition/mixins/supports_filtering_and_aggregation.rbs b/elasticgraph-schema_definition/sig/elastic_graph/schema_definition/mixins/supports_filtering_and_aggregation.rbs
@@ -7,6 +7,7 @@ module ElasticGraph
         def type_ref: () -> SchemaElements::TypeReference
         def mapping_options: () -> HasTypeInfo::optionsHash
         def root_document_type?: () -> bool
+        def directly_queryable?: () -> bool
         def abstract?: () -> bool
         def graphql_only?: () -> bool
         def runtime_metadata: (::Array[SchemaArtifacts::RuntimeMetadata::UpdateTarget]) -> SchemaArtifacts::RuntimeMetadata::ObjectType
diff --git a/elasticgraph-schema_definition/sig/elastic_graph/schema_definition/rake_tasks.rbs b/elasticgraph-schema_definition/sig/elastic_graph/schema_definition/rake_tasks.rbs
@@ -30,6 +30,8 @@ module ElasticGraph
 
       def define_tasks: () -> void
       def schema_artifact_manager: () -> SchemaArtifactManager
+
+      @schema_def_api: API?
       def schema_def_api: () -> API
     end
   end
diff --git a/elasticgraph-schema_definition/sig/elastic_graph/schema_definition/schema_elements/field.rbs b/elasticgraph-schema_definition/sig/elastic_graph/schema_definition/schema_elements/field.rbs
@@ -62,6 +62,7 @@ module ElasticGraph
         def filterable?: () -> bool
         def groupable?: () -> bool
         def highlightable?: () -> bool
+        def returnable?: () -> bool
         def list_field_groupable_by_single_values?: () -> bool
         def aggregatable?: () -> bool
         def sub_aggregatable?: () -> bool
diff --git a/elasticgraph-schema_definition/sig/elastic_graph/schema_definition/scripting/file_system_repository.rbs b/elasticgraph-schema_definition/sig/elastic_graph/schema_definition/scripting/file_system_repository.rbs
@@ -16,7 +16,7 @@ module ElasticGraph
 
         private
 
-        def verify_no_duplicates!: (::Array[Script]) -> (void | bot)
+        def verify_no_duplicates!: (::Array[Script]) -> void
       end
     end
   end
diff --git a/elasticgraph-schema_definition/sig/elastic_graph/schema_definition/state.rbs b/elasticgraph-schema_definition/sig/elastic_graph/schema_definition/state.rbs
@@ -9,6 +9,7 @@ module ElasticGraph
       attr_reader scalar_types_by_name: ::Hash[::String, SchemaElements::ScalarType]
       attr_reader enum_types_by_name: ::Hash[::String, SchemaElements::EnumType]
       attr_reader implementations_by_interface_ref: ::Hash[SchemaElements::TypeReference, ::Set[SchemaElements::TypeWithSubfields]]
+      attr_reader union_types_by_member_ref: ::Hash[SchemaElements::TypeReference, ::Set[SchemaElements::UnionType]]
       attr_reader sdl_parts: ::Array[::String]
       attr_reader paginated_collection_element_types: ::Set[::String]
       attr_reader user_defined_fields: ::Set[SchemaElements::Field]
@@ -43,6 +44,7 @@ module ElasticGraph
         scalar_types_by_name: ::Hash[::String, SchemaElements::ScalarType],
         enum_types_by_name: ::Hash[::String, SchemaElements::EnumType],
         implementations_by_interface_ref: ::Hash[SchemaElements::TypeReference, ::Set[SchemaElements::TypeWithSubfields]],
+        union_types_by_member_ref: ::Hash[SchemaElements::TypeReference, ::Set[SchemaElements::UnionType]],
         sdl_parts: ::Array[::String],
         paginated_collection_element_types: ::Set[::String],
         user_defined_fields: ::Set[SchemaElements::Field],
diff --git a/elasticgraph-support/lib/elastic_graph/support/config.rb b/elasticgraph-support/lib/elastic_graph/support/config.rb
@@ -45,7 +45,7 @@ module Config
       #    end
       def self.define(*attrs, &block)
         ::Data.define(*attrs) do
-          # @implements ::Data
+          # @implements ConfigData
           alias_method :__data_initialize, :initialize
           extend ClassMethods
 
diff --git a/elasticgraph-support/sig/elastic_graph/support/config.rbs b/elasticgraph-support/sig/elastic_graph/support/config.rbs
@@ -3,6 +3,14 @@ module ElasticGraph
     module Config
       def self.define: [T] (*::Symbol) ?{ (ClassMethods[T]) -> void } -> T
 
+      class ConfigData < Data
+        def initialize: (**untyped) -> void
+
+        private
+
+        def convert_values: (**untyped) -> ::Hash[::Symbol, untyped]
+      end
+
       module ClassMethods[T]: ::Class
         attr_reader validator: Support::JSONSchema::Validator
         attr_reader path: ::String
@@ -14,14 +22,6 @@ module ElasticGraph
         def raise_invalid_config: (::String) -> bot
         def new_without_validation: (**untyped) -> T
       end
-
-      module InstanceMethods: Data
-        def initialize: (**untyped) -> void
-
-        private
-
-        def convert_values: (**untyped) -> ::Hash[::Symbol, untyped]
-      end
     end
   end
 end
diff --git a/rbs_collection.lock.yaml b/rbs_collection.lock.yaml
diff --git a/rbs_collection.yaml b/rbs_collection.yaml
