Improved type generation + agent context + CI.

Author: samuel-williams-shopify

.github/workflows/test-types.yaml

@@ -0,0 +1,33 @@
+name: Test Types
+
+on: [push, pull_request]
+
+permissions:
+  contents: read
+
+env:
+  CONSOLE_OUTPUT: XTerm
+
+jobs:
+  test:
+    name: ${{matrix.ruby}} on ${{matrix.os}}
+    runs-on: ${{matrix.os}}-latest
+    
+    strategy:
+      matrix:
+        os:
+          - ubuntu
+        
+        ruby:
+          - "3.4"
+    
+    steps:
+    - uses: actions/checkout@v4
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{matrix.ruby}}
+        bundler-cache: true
+    
+    - name: Run tests
+      timeout-minutes: 10
+      run: bundle exec steep check lib

context/types.md

@@ -0,0 +1,75 @@
+# Setting Up RBS Types and Steep Type Checking for Ruby Gems
+
+This guide covers the process for establishing robust type checking in Ruby gems using RBS and Steep, focusing on automated generation from source documentation and proper validation.
+
+## Core Process
+
+### Documentation-Driven RBS Generation
+
+Generate RBS files from documentation:
+
+```bash
+bake decode:rbs:generate lib > sig/example/gem.rbs`
+```
+
+At a minimum, add `@parameter`, `@attribute` and `@returns` documentation to all public methods.
+
+#### Parametric Types
+
+Use `@rbs generic` comments to define type parameters for classes and modules:
+
+```ruby
+# @rbs generic T
+class Container
+	# @parameter item [T] The item to store
+	def initialize(item)
+		@item = item
+	end
+	
+	# @returns [T] The stored item
+	def get
+		@item
+	end
+end
+```
+
+Use `@rbs` comments for parametric method signatures:
+
+```ruby
+# From above:
+class Container
+	# @rbs () { (T) -> void } -> void
+	def each
+		yield @item
+	end
+```
+
+#### Interfaces
+
+Create interfaces in `sig/example/gem/interface.rbs`:
+
+```rbs
+module Example
+	module Gem
+		interface _Interface
+		end
+	end
+end
+```
+
+You can use the interface in `@parameter`, `@attribute` and `@returns` types.
+
+### Testing
+
+Run tests using the `steep` gem.
+
+```bash
+steep check
+```
+
+**Process**: Start with basic generation, then refine based on Steep feedback.
+
+1. Generate initial RBS from documentation
+2. Run `steep check lib` to identify issues
+3. Fix structural problems (inheritance, missing docs)
+4. Iterate until clean validation

gems.rb

@@ -25,6 +25,8 @@
 	gem "rubocop"
 	gem "rubocop-socketry"
 
+	gem "steep"
+	
 	gem "bake-test"
 	gem "bake-test-external"
 

lib/decode/definition.rb

@@ -106,12 +106,14 @@ def nested_name
 		end
 
 		# Does the definition name match the specified prefix?
+		# @parameter prefix [String] The prefix to match against.
 		# @returns [Boolean]
 		def start_with?(prefix)
 			self.nested_name.start_with?(prefix)
 		end
 
 		# Convert this definition into another kind of definition.
+		# @parameter kind [Symbol] The kind to convert to.
 		def convert(kind)
 			raise ArgumentError, "Unable to convert #{self} into #{kind}!"
 		end

lib/decode/language/reference.rb

@@ -9,6 +9,8 @@ module Language
 		class Reference
 			# Initialize the reference.
 			# @parameter identifier [String] The identifier part of the reference.
+			# @parameter language [Language::Generic] The language this reference belongs to.
+			# @parameter lexical_path [Array(String) | nil] The lexical path scope for resolution.
 			def initialize(identifier, language, lexical_path = nil)
 				@identifier = identifier
 				@language = language

lib/decode/language/ruby/reference.rb

@@ -12,7 +12,7 @@ module Ruby
 			class Reference < Language::Reference
 				# Create a reference from a constant node.
 				# @parameter node [Prism::Node] The constant node.
-				# @parameter language [Language] The language instance.
+				# @parameter language [Language::Generic] The language instance.
 				def self.from_const(node, language)
 					lexical_path = append_const(node)
 
@@ -22,6 +22,7 @@ def self.from_const(node, language)
 				# Append a constant node to the path.
 				# @parameter node [Prism::Node] The constant node.
 				# @parameter path [Array] The path to append to.
+				# @returns [Array] The path with constant information appended.
 				def self.append_const(node, path = [])
 					case node.type
 					when :constant_read_node

lib/decode/rbs/class.rb

@@ -27,7 +27,7 @@ def generics
 			# Convert the class definition to RBS AST
 			def to_rbs_ast(method_definitions = [], index = nil)
 				name = simple_name_to_rbs(@definition.name)
-				comment = extract_comment(@definition)
+				comment = self.comment
 
 				# Extract generics from RBS tags
 				type_params = generics.map do |generic|
@@ -78,9 +78,16 @@ def simple_name_to_rbs(name)
 			def qualified_name_to_rbs(qualified_name)
 				parts = qualified_name.split("::")
 				name = parts.pop
-				namespace = ::RBS::Namespace.new(path: parts.map(&:to_sym), absolute: true)
 
-				::RBS::TypeName.new(name: name.to_sym, namespace: namespace)
+				# For simple names (no ::), create relative references within current namespace
+				if parts.empty?
+					::RBS::TypeName.new(name: name.to_sym, namespace: ::RBS::Namespace.empty)
+				else
+					# For qualified names within the same root namespace, use relative references
+					# This handles cases like Comment::Node, Language::Generic within Decode module
+					namespace = ::RBS::Namespace.new(path: parts.map(&:to_sym), absolute: false)
+					::RBS::TypeName.new(name: name.to_sym, namespace: namespace)
+				end
 			end
 
 		end

lib/decode/rbs/method.rb

@@ -6,17 +6,20 @@
 require "rbs"
 require "console"
 require_relative "wrapper"
+require_relative "type"
 
 module Decode
 	module RBS
 		# Represents a Ruby method definition wrapper for RBS generation.
 		class Method < Wrapper
-			
 			# Initialize a new method wrapper.
 			# @parameter definition [Decode::Definition] The method definition to wrap.
 			def initialize(definition)
 				super
 				@signatures = nil
+				@keyword_arguments = nil
+				@return_type = nil
+				@parameters = nil
 			end
 
 			# Extract method signatures from the method definition.
@@ -25,10 +28,28 @@ def signatures
 				@signatures ||= extract_signatures
 			end
 
+			# Extract keyword arguments from the method definition.
+			# @returns [Hash] Hash with :required and :optional keys.
+			def keyword_arguments
+				@keyword_arguments ||= extract_keyword_arguments(@definition, nil)
+			end
+			
+			# Extract return type from the method definition.
+			# @returns [::RBS::Types::t] The RBS return type.
+			def return_type
+				@return_type ||= extract_return_type(@definition, nil) || ::RBS::Parser.parse_type("untyped")
+			end
+			
+			# Extract parameters from the method definition.
+			# @returns [Array] Array of RBS parameter objects.
+			def parameters
+				@parameters ||= extract_parameters(@definition, nil)
+			end
+			
 			# Convert the method definition to RBS AST
 			def to_rbs_ast(index = nil)
 				method_name = @definition.name
-				comment = extract_comment(@definition)
+				comment = self.comment
 
 				overloads = []
 				if signatures.any?
@@ -40,8 +61,9 @@ def to_rbs_ast(index = nil)
 						)
 					end
 				else
-					return_type = extract_return_type(@definition, index) || ::RBS::Parser.parse_type("untyped")
-					parameters = extract_parameters(@definition, index)
+					return_type = self.return_type
+					parameters = self.parameters
+					keywords = self.keyword_arguments
 					block_type = extract_block_type(@definition, index)
 
 					method_type = ::RBS::MethodType.new(
@@ -51,8 +73,8 @@ def to_rbs_ast(index = nil)
 							optional_positionals: [],
 							rest_positionals: nil,
 							trailing_positionals: [],
-							required_keywords: {},
-							optional_keywords: {},
+							required_keywords: keywords[:required],
+							optional_keywords: keywords[:optional],
 							rest_keywords: nil,
 							return_type: return_type
 						),
@@ -91,13 +113,23 @@ def extract_return_type(definition, index)
 				# Look for @returns tags in the method's documentation
 				documentation = definition.documentation
 
-				# Find @returns tag
-				returns_tag = documentation&.filter(Decode::Comment::Returns)&.first
+				# Find all @returns tags
+				returns_tags = documentation&.filter(Decode::Comment::Returns)&.to_a
 
-				if returns_tag
-					# Parse the type from the tag
-					type_string = returns_tag.type.strip
-					parse_type_string(type_string)
+				if returns_tags&.any?
+					if returns_tags.length == 1
+						# Single return type
+						type_string = returns_tags.first.type.strip
+						Type.parse(type_string)
+					else
+						# Multiple return types - create union
+						types = returns_tags.map do |tag|
+							type_string = tag.type.strip
+							Type.parse(type_string)
+						end
+						
+						::RBS::Types::Union.new(types: types, location: nil)
+					end
 				else
 					# Infer return type based on method name patterns
 					infer_return_type(definition)
@@ -109,14 +141,15 @@ def extract_parameters(definition, index)
 				documentation = definition.documentation
 				return [] unless documentation
 
-				# Find @parameter tags
+				# Find @parameter tags (but not @option tags, which are handled separately)
 				param_tags = documentation.filter(Decode::Comment::Parameter).to_a
+				param_tags = param_tags.reject {|tag| tag.is_a?(Decode::Comment::Option)}
 				return [] if param_tags.empty?
 
 				param_tags.map do |tag|
 					name = tag.name
 					type_string = tag.type.strip
-					type = parse_type_string(type_string)
+					type = Type.parse(type_string)
 
 					::RBS::Types::Function::Param.new(
 						type: type,
@@ -125,6 +158,38 @@ def extract_parameters(definition, index)
 				end
 			end
 
+			# Extract keyword arguments from @option tags
+			def extract_keyword_arguments(definition, index)
+				documentation = definition.documentation
+				return { required: {}, optional: {} } unless documentation
+				
+				# Find @option tags
+				option_tags = documentation.filter(Decode::Comment::Option).to_a
+				return { required: {}, optional: {} } if option_tags.empty?
+				
+				keywords = { required: {}, optional: {} }
+				
+				option_tags.each do |tag|
+					name = tag.name.to_s
+					# Remove leading colon if present (e.g., ":cached" -> "cached")
+					name = name.sub(/\A:/, "")
+					
+					type_string = tag.type.strip
+					type = Type.parse(type_string)
+					
+					# Determine if the keyword is optional based on the type annotation
+					# If the type is nullable (contains nil or ends with ?), make it optional
+					if Type.nullable?(type)
+						keywords[:optional][name.to_sym] = type
+					else
+						keywords[:required][name.to_sym] = type
+					end
+				end
+				
+				keywords
+			end
+			
+			
 			# Extract block type from method documentation
 			def extract_block_type(definition, index)
 				documentation = definition.documentation
@@ -138,7 +203,7 @@ def extract_block_type(definition, index)
 				block_params = yields_tag.filter(Decode::Comment::Parameter).map do |param_tag|
 					name = param_tag.name
 					type_string = param_tag.type.strip
-					type = parse_type_string(type_string)
+					type = Type.parse(type_string)
 
 					::RBS::Types::Function::Param.new(
 						type: type,
@@ -199,19 +264,6 @@ def infer_return_type(definition)
 				::RBS::Parser.parse_type("untyped")
 			end
 
-			# Parse a type string and convert it to RBS type
-			def parse_type_string(type_string)
-				# This is for backwards compatibility with the old syntax, eventually we will emit warnings for these:
-				type_string = type_string.tr("()", "[]")
-				type_string.gsub!("| Nil", "| nil")
-				type_string.gsub!("Boolean", "bool")
-				
-				return ::RBS::Parser.parse_type(type_string)
-			rescue => error
-				Console.warn(self, "Failed to parse type string: #{type_string}", error)
-				return ::RBS::Parser.parse_type("untyped")
-			end
-			
 		end
 	end
 end

lib/decode/rbs/module.rb

@@ -20,7 +20,7 @@ def initialize(definition)
 			# Convert the module definition to RBS AST
 			def to_rbs_ast(method_definitions = [], index = nil)
 				name = simple_name_to_rbs(@definition.name)
-				comment = extract_comment(@definition)
+				comment = self.comment
 
 				# Build method definitions
 				methods = method_definitions.map{|method_def| Method.new(method_def).to_rbs_ast(index)}.compact