decode 0.24.3 → 0.24.5

data/lib/decode/rbs/module.rb

@@ -5,6 +5,8 @@
 
 require "rbs"
 require_relative "wrapper"
+require_relative "method"
+require_relative "type"
 
 module Decode
 	module RBS
@@ -18,18 +20,29 @@ module Decode
 			end
 			
 			# Convert the module definition to RBS AST
-			def to_rbs_ast(method_definitions = [], index = nil)
+			# @parameter method_definitions [Array(Method)] The method definitions to convert.
+			# @parameter constant_definitions [Array(Constant)] The constant definitions to convert.
+			# @parameter attribute_definitions [Array(Attribute)] The attribute definitions to convert.
+			# @parameter index [Index?] The index for resolving references.
+			# @returns [RBS::AST::Declarations::Module] The RBS AST for the module.
+			def to_rbs_ast(method_definitions = [], constant_definitions = [], attribute_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
 				
+				# Build constant definitions:
+				constants = constant_definitions.map{|const_def| build_constant_rbs(const_def)}.compact
+				
+				# Build attribute definitions and infer instance variable types:
+				attributes, instance_variables = build_attributes_rbs(attribute_definitions)
+				
 				::RBS::AST::Declarations::Module.new(
 					name: name,
 					type_params: [],
 					self_types: [],
-					members: methods,
+					members: constants + attributes + instance_variables + methods,
 					annotations: [],
 					location: nil,
 					comment: comment
@@ -38,11 +51,74 @@ module Decode
 			
 			private
 			
-			# Convert a simple name to RBS TypeName (not qualified)
+			# Build a constant RBS declaration.
+			def build_constant_rbs(constant_definition)
+				# Look for @constant tags in the constant's documentation:
+				documentation = constant_definition.documentation
+				constant_tags = documentation&.filter(Decode::Comment::Constant)&.to_a
+				
+				if constant_tags&.any?
+					type_string = constant_tags.first.type.strip
+					type = ::Decode::RBS::Type.parse(type_string)
+					
+					::RBS::AST::Declarations::Constant.new(
+					name: constant_definition.name.to_sym,
+					type: type,
+					location: nil,
+					comment: nil
+				)
+				end
+			end
+			
+			# Convert a simple name to RBS TypeName (not qualified).
 			def simple_name_to_rbs(name)
 				::RBS::TypeName.new(name: name.to_sym, namespace: ::RBS::Namespace.empty)
 			end
 			
+			# Build attribute RBS declarations and infer instance variable types.
+			# @parameter attribute_definitions [Array] Array of Attribute definition objects
+			# @returns [Array] A tuple of [attribute_declarations, instance_variable_declarations]
+			def build_attributes_rbs(attribute_definitions)
+				attributes = []
+				instance_variables = []
+				
+				# Create a mapping from attribute names to their types:
+				attribute_types = {}
+				
+				attribute_definitions.each do |attribute_definition|
+					# Extract @attribute type annotation from documentation:
+					documentation = attribute_definition.documentation
+					attribute_tags = documentation&.filter(Decode::Comment::Attribute)&.to_a
+					
+					if attribute_tags&.any?
+						type_string = attribute_tags.first.type.strip
+						type = ::Decode::RBS::Type.parse(type_string)
+						
+						attribute_types[attribute_definition.name] = type
+						
+						# Generate attr_reader RBS declaration:
+						attributes << ::RBS::AST::Members::AttrReader.new(
+							name: attribute_definition.name.to_sym,
+							type: type,
+							ivar_name: :"@#{attribute_definition.name}",
+							kind: :instance,
+							annotations: [],
+							location: nil,
+							comment: nil
+						)
+						
+						# Generate instance variable declaration:
+						instance_variables << ::RBS::AST::Members::InstanceVariable.new(
+							name: :"@#{attribute_definition.name}",
+							type: type,
+							location: nil,
+							comment: nil
+						)
+					end
+				end
+				
+				[attributes, instance_variables]
+			end
 		end
 	end
-end 
+end

data/lib/decode/rbs/type.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024, by Samuel Williams.
+
+require "rbs"
+require "console"
+
+module Decode
+	module RBS
+		# Utilities for working with RBS types.
+		module Type
+			# Check if an RBS type represents a nullable/optional type
+			# This method recursively traverses the type tree to find nil anywhere
+			# @parameter rbs_type [untyped] The RBS type to check for nullability.
+			# @returns [bool] True if the type can be nil, false otherwise.
+			def self.nullable?(rbs_type)
+				case rbs_type
+				when ::RBS::Types::Optional
+					# Type? form - directly optional
+					true
+				when ::RBS::Types::Union
+					# Type | nil form - recursively check all union members
+					rbs_type.types.any? {|type| nullable?(type)}
+				when ::RBS::Types::Tuple
+					# [Type] form - recursively check all tuple elements
+					rbs_type.types.any? {|type| nullable?(type)}
+				when ::RBS::Types::Bases::Nil
+					# Direct nil type
+					true
+				else
+					false
+				end
+			end
+			
+			# Parse a type string and convert it to RBS type
+			# @parameter type_string [String] The type string to parse.
+			# @returns [untyped] The parsed RBS type object.
+			def self.parse(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!(/\s*\| Nil/, "?")
+				type_string.gsub!("Boolean", "bool")
+				
+				return ::RBS::Parser.parse_type(type_string)
+			rescue => error
+				warn("Failed to parse type string: #{type_string}") if $DEBUG
+				return ::RBS::Parser.parse_type("untyped")
+			end
+		end
+	end
+end 

data/lib/decode/rbs/wrapper.rb

@@ -14,6 +14,7 @@ module Decode
 			def initialize(definition)
 				@definition = definition
 				@tags = nil
+				@comment = nil
 			end
 			
 			# Extract RBS tags from the definition's documentation.
@@ -22,6 +23,12 @@ module Decode
 				@tags ||= extract_tags
 			end
 			
+			# Extract comment from the definition's documentation.
+			# @returns [RBS::AST::Comment?] The RBS comment object.
+			def comment
+				@comment ||= extract_comment
+			end
+			
 			private
 			
 			# Extract RBS tags from the definition's documentation.
@@ -34,13 +41,13 @@ module Decode
 			
 			# Extract comment from definition documentation.
 			# @parameter definition [Definition] The definition to extract comment from (defaults to @definition).
-			# @returns [RBS::AST::Comment, nil] The extracted comment or nil if no documentation.
+			# @returns [RBS::AST::Comment?] The extracted comment or nil if no documentation.
 			def extract_comment(definition = @definition)
 				documentation = definition.documentation
 				return nil unless documentation
 				
 				# Extract the main description text (non-tag content)
-				comment_lines = []
+				comment_lines = [] #: Array[String]
 				
 				documentation.children&.each do |child|
 					if child.is_a?(Decode::Comment::Text)
@@ -61,4 +68,4 @@ module Decode
 			end
 		end
 	end
-end 
+end

data/lib/decode/scope.rb

@@ -10,11 +10,11 @@ module Decode
 	class Scope < Definition
 		# @returns [String] The name of the scope.
 		def short_form
-			@name
+			name.to_s
 		end
 		
 		# Scopes are always containers.
-		# @returns [Boolean] Always `true`.
+		# @returns [bool] Always `true`.
 		def container?
 			true
 		end

data/lib/decode/segment.rb

@@ -20,6 +20,7 @@ module Decode
 		def initialize(comments, language)
 			@comments = comments
 			@language = language
+			@documentation = nil
 		end
 		
 		# @attribute [Array(String)] The preceeding comments.
@@ -29,7 +30,7 @@ module Decode
 		attr :language
 		
 		# An interface for accsssing the documentation of the definition.
-		# @returns [Documentation | Nil] A {Documentation} instance if this definition has comments.
+		# @returns [Documentation?] A {Documentation} instance if this definition has comments.
 		def documentation
 			if @comments&.any?
 				@documentation ||= Documentation.new(@comments, @language)
@@ -37,7 +38,7 @@ module Decode
 		end
 		
 		# The source code trailing the comments.
-		# @returns [String | Nil]
+		# @returns [String?]
 		def code
 		end
 	end

data/lib/decode/source.rb

@@ -13,24 +13,15 @@ module Decode
 		# @parameter language [Language::Generic] The language parser to use.
 		def initialize(path, language)
 			@path = path
-			@buffer = nil
 			@language = language
+			
+			@buffer = nil
 		end
 		
 		# The path of the source file.
-		# @attribute [String] A file-system path to the source file.
+		# @attribute [StringPath] A file-system path to the source file.
 		attr :path
 		
-		# The relative path of the source, if it is known.
-		# @returns [String] The relative path or the full path if relative path is unknown.
-		def relative_path
-			if @path.respond_to?(:relative_path)
-				@path.relative_path
-			else
-				@path
-			end
-		end
-		
 		# The language of the source file.
 		# @attribute [Language::Generic] The language parser for this source.
 		attr :language
@@ -62,8 +53,8 @@ module Decode
 		end
 		
 		# Generate code representation with optional index for link resolution.
-		# @parameter index [Index] Optional index for resolving links.
-		# @parameter relative_to [Definition] Optional definition to resolve relative references.
+		# @parameter index [Index?] Optional index for resolving links.
+		# @parameter relative_to [Definition?] Optional definition to resolve relative references.
 		# @returns [String] The formatted code representation.
 		def code(index = nil, relative_to: nil)
 			@language.code_for(self.read, index, relative_to: relative_to)

data/lib/decode/syntax/rewriter.rb

@@ -14,19 +14,22 @@ module Decode
 				@matches = []
 			end
 			
+			# @attribute [String] The text to rewrite.
 			attr :text
 			
+			# @attribute [Array[Match]] The matches to apply.
 			attr :matches
 			
 			# Add a match to the rewriter.
 			# @parameter match [Match] The match to add.
 			def << match
 				@matches << match
+				return self
 			end
 			
 			# Returns a chunk of raw text with no formatting.
 			def text_for(range)
-				@text[range]
+				@text[range] || ""
 			end
 			
 			# Apply all matches to generate the rewritten output.

data/lib/decode/trie.rb

@@ -7,13 +7,14 @@ require_relative "source"
 
 module Decode
 	# Represents a prefix-trie data structure for fast lexical lookups.
+	# @rbs generic T
 	class Trie
 		# Represents a single node in the trie.
 		class Node
-			# Initialize a new trie node.
+			# Initialize an empty node.
 			def initialize
+				@children = {}
 				@values = nil
-				@children = Hash.new
 			end
 			
 			# Generate a string representation of this node.
@@ -26,17 +27,17 @@ module Decode
 			alias to_s inspect
 			
 			# A mutable array of all values that terminate at this node.
-			# @attribute [Array | Nil] The values stored at this node, or nil if no values.
+			# @attribute [Array[T]?] The values stored at this node, or nil if no values.
 			attr_accessor :values
 			
 			# A hash table of all children nodes, indexed by name.
-			# @attribute [Hash(String, Node)] Child nodes indexed by their path component.
+			# @attribute [Hash(Symbol, Node)] Child nodes indexed by their path component.
 			attr :children
 			
 			# Look up a lexical path starting at this node.
-			# @parameter path [Array(String)] The path to resolve.
+			# @parameter path [Array(Symbol)] The path to resolve.
 			# @parameter index [Integer] The current index in the path (used for recursion).
-			# @returns [Node | Nil] The node at the specified path, or nil if not found.
+			# @returns [Node?] The node at the specified path, or nil if not found.
 			def lookup(path, index = 0)
 				if index < path.size
 					if child = @children[path[index]]
@@ -49,11 +50,12 @@ module Decode
 			
 			# Traverse the trie from this node.
 			# Invoke `descend.call` to traverse the children of the current node.
-			# @parameter path [Array(String)] The current lexical path.
+			# @parameter path [Array(Symbol)] The current lexical path.
 			# @yields {|path, node, descend| ...} Called for each node during traversal.
-			#   @parameter path [Array(String)] The current lexical path.
+			#   @parameter path [Array(Symbol)] The current lexical path.
 			#   @parameter node [Node] The current node which is being traversed.
 			#   @parameter descend [Proc] The recursive method for traversing children.
+			# @rbs (?Array[Symbol]) { (Array[Symbol], Node, Proc) -> void } -> void
 			def traverse(path = [], &block)
 				descend = lambda do
 					@children.each do |name, node|
@@ -75,8 +77,8 @@ module Decode
 		attr :root
 		
 		# Insert the specified value at the given path into the trie.
-		# @parameter path [Array(String)] The lexical path where the value will be inserted.
-		# @parameter value [Object] The value to insert at the specified path.
+		# @parameter path [Array(Symbol)] The lexical path where the value will be inserted.
+		# @parameter value [T] The value to insert at the specified path.
 		def insert(path, value)
 			node = @root
 			
@@ -86,24 +88,29 @@ module Decode
 			end
 			
 			# Add the value to the target node:
-			(node.values ||= []) << value
+			if node.values
+				node.values << value
+			else
+				node.values = [value]
+			end
 		end
 		
 		# Lookup the values at the specified path.
-		# @parameter path [Array(String)] The lexical path which contains the values.
-		# @returns [Node | Nil] The node at the specified path, or nil if not found.
+		# @parameter path [Array(Symbol)] The lexical path which contains the values.
+		# @returns [Node?] The node at the specified path, or nil if not found.
 		def lookup(path)
 			@root.lookup(path)
 		end
 		
 		# Enumerate all lexical scopes under the specified path.
-		# @parameter path [Array(String)] The starting path to enumerate from.
+		# @parameter path [Array(Symbol)] The starting path to enumerate from.
 		# @yields {|path, values| ...} Called for each path with values.
-		#   @parameter path [Array(String)] The lexical path.
-		#   @parameter values [Array(Object) | Nil] The values that exist at the given path.
+		#   @parameter path [Array(Symbol)] The lexical path.
+		#   @parameter values [Array[T]?] The values that exist at the given path.
+		# @rbs (?Array[Symbol]) { (Array[Symbol], (Array[T] | nil)) -> void } -> void
 		def each(path = [], &block)
-			if node = @root.lookup(path)
-				node.traverse do |path, node, descend|
+			if node = @root.lookup(path, 0)
+				node.traverse(path) do |path, node, descend|
 					yield path, node.values
 					
 					descend.call
@@ -113,11 +120,12 @@ module Decode
 		
 		# Traverse the trie starting from the specified path.
 		# See {Node#traverse} for details.
-		# @parameter path [Array(String)] The starting path to traverse from.
+		# @parameter path [Array(Symbol)] The starting path to traverse from.
 		# @yields {|path, node, descend| ...} Called for each node during traversal.
+		# @rbs (?Array[Symbol]) { (Array[Symbol], Node, Proc) -> void } -> void
 		def traverse(path = [], &block)
 			if node = @root.lookup(path)
-				node.traverse(&block)
+				node.traverse(path, &block)
 			end
 		end
 	end

data/lib/decode/version.rb

@@ -4,5 +4,6 @@
 # Copyright, 2020-2025, by Samuel Williams.
 
 module Decode
-	VERSION = "0.24.3"
+	# @constant [String] The version of the gem.
+	VERSION = "0.24.5"
 end

data/readme.md

@@ -22,6 +22,12 @@ Please see the [project documentation](https://socketry.github.io/decode/) for m
 
 Please see the [project releases](https://socketry.github.io/decode/releases/index) for all releases.
 
+### v0.24.4
+
+  - Add support for `@constant [Type] Description.` tags.
+  - Add support for instance variable type inference from `@attribute` tags.
+  - Add support for method visibility in RBS output.
+
 ### v0.24.0
 
   - [Introduce support for RBS signature generation](https://socketry.github.io/decode/releases/index#introduce-support-for-rbs-signature-generation)

data/releases.md

@@ -1,5 +1,11 @@
 # Releases
 
+## v0.24.4
+
+  - Add support for `@constant [Type] Description.` tags.
+  - Add support for instance variable type inference from `@attribute` tags.
+  - Add support for method visibility in RBS output.
+
 ## v0.24.0
 
 ### Introduce support for RBS signature generation