decode 0.24.2 → 0.24.4

data/lib/decode/language/ruby/parser.rb

@@ -25,7 +25,7 @@ module Decode
 			# The Ruby source code parser.
 			class Parser
 				# Initialize a new Ruby parser.
-				# @parameter language [Language] The language instance.
+				# @parameter language [Language::Generic] The language instance.
 				def initialize(language)
 					@language = language
 					
@@ -33,7 +33,26 @@ module Decode
 					@definitions = Hash.new.compare_by_identity
 				end
 				
+				# @attribute [Language::Generic] The language instance.
+				attr :language
+				
+				# @attribute [Symbol] The current visibility mode.
+				attr :visibility
+				
+				# @attribute [Hash] Cache for definition lookups.
+				attr :definitions
+				
+				# Parse the source code using Prism.
+				# @parameter source [Source] The source to parse.
+				# @returns [untyped] The parsed syntax tree.
+				def parse_source(source)
+					text = source.read
+					return ::Prism.parse(text)
+				end
+				
 				# Extract definitions from the given input file.
+				# @parameter source [Source] The source file to parse.
+				# @returns [Enumerator[Definition]] An enumerator of definitions.
 				def definitions_for(source, &block)
 					return enum_for(:definitions_for, source) unless block_given?
 					
@@ -46,6 +65,9 @@ module Decode
 				end
 				
 				# Walk over the syntax tree and extract relevant definitions with their associated comments.
+				# @parameter node [untyped] The syntax tree node to walk.
+				# @parameter parent [Definition?] The parent definition.
+				# @parameter source [Source?] The source file for location tracking.
 				def walk_definitions(node, parent = nil, source = nil, &block)
 					# Check for scope definitions from comments
 					if node.comments.any?
@@ -71,13 +93,13 @@ module Decode
 						path = nested_path_for(node.constant_path)
 						
 						definition = Module.new(path,
-							visibility: :public,
-							comments: comments_for(node),
-							parent: parent,
-							node: node,
-							language: @language,
-							source: source,
-						)
+									visibility: :public,
+									comments: comments_for(node),
+									parent: parent,
+									node: node,
+									language: @language,
+									source: source,
+								)
 						
 						store_definition(parent, path.last.to_sym, definition)
 						yield definition
@@ -92,14 +114,14 @@ module Decode
 						super_class = nested_name_for(node.superclass)
 						
 						definition = Class.new(path,
-							super_class: super_class,
-							visibility: :public, 
-							comments: comments_for(node),
-							parent: parent,
-							node: node,
-							language: @language,
-							source: source,
-						)
+									super_class: super_class,
+									visibility: :public, 
+									comments: comments_for(node),
+									parent: parent,
+									node: node,
+									language: @language,
+									source: source,
+								)
 						
 						store_definition(parent, path.last.to_sym, definition)
 						yield definition
@@ -112,13 +134,13 @@ module Decode
 					when :singleton_class_node
 						if name = singleton_name_for(node)
 							definition = Singleton.new(name,
-								comments: comments_for(node),
-								parent: parent,
-								node: node,
-								language: @language,
-								visibility: :public,
-								source: source
-							)
+										comments: comments_for(node),
+										parent: parent,
+										node: node,
+										language: @language,
+										visibility: :public,
+										source: source
+									)
 							
 							yield definition
 							
@@ -130,23 +152,23 @@ module Decode
 						receiver = receiver_for(node.receiver)
 						
 						definition = Method.new(node.name,
-							visibility: @visibility,
-							comments: comments_for(node),
-							parent: parent,
-							node: node,
-							language: @language,
-							receiver: receiver,
-							source: source,
-						)
+									visibility: @visibility,
+									comments: comments_for(node),
+									parent: parent,
+									node: node,
+									language: @language,
+									receiver: receiver,
+									source: source,
+								)
 						
 						yield definition
 					when :constant_write_node
 						definition = Constant.new(node.name,
-							comments: comments_for(node),
-							parent: parent,
-							node: node,
-							language: @language,
-						)
+									comments: comments_for(node),
+									parent: parent,
+									node: node,
+									language: @language,
+								)
 						
 						store_definition(parent, node.name, definition)
 						yield definition
@@ -165,13 +187,13 @@ module Decode
 										receiver = receiver_for(argument_node.receiver)
 										
 										definition = Method.new(argument_node.name,
-											visibility: name,
-											comments: comments_for(argument_node),
-											parent: parent,
-											node: argument_node,
-											language: @language,
-											receiver: receiver,
-										)
+													visibility: name,
+													comments: comments_for(argument_node),
+													parent: parent,
+													node: argument_node,
+													language: @language,
+													receiver: receiver,
+												)
 										
 										yield definition
 									end
@@ -195,9 +217,9 @@ module Decode
 							end
 						when :attr, :attr_reader, :attr_writer, :attr_accessor
 							definition = Attribute.new(attribute_name_for(node),
-								comments: comments_for(node),
-								parent: parent, language: @language, node: node
-							)
+										comments: comments_for(node),
+										parent: parent, language: @language, node: node
+									)
 							
 							yield definition
 						when :alias_method
@@ -211,13 +233,13 @@ module Decode
 								old_name = symbol_name_for(old_name_arg)
 								
 								definition = Alias.new(new_name.to_sym, old_name.to_sym,
-									comments: comments_for(node),
-									parent: parent,
-									node: node,
-									language: @language,
-									visibility: @visibility,
-									source: source,
-								)
+											comments: comments_for(node),
+											parent: parent,
+											node: node,
+											language: @language,
+											visibility: @visibility,
+											source: source,
+										)
 								
 								yield definition
 							end
@@ -230,10 +252,10 @@ module Decode
 							
 							if has_name_comment || has_attribute_comment || has_block
 								definition = Call.new(
-									attribute_name_for(node),
-									comments: comments_for(node),
-									parent: parent, language: @language, node: node
-								)
+											attribute_name_for(node),
+											comments: comments_for(node),
+											parent: parent, language: @language, node: node
+										)
 								
 								yield definition
 								
@@ -249,13 +271,13 @@ module Decode
 						old_name = node.old_name.unescaped
 						
 						definition = Alias.new(new_name.to_sym, old_name.to_sym,
-							comments: comments_for(node),
-							parent: parent,
-							node: node,
-							language: @language,
-							visibility: @visibility,
-							source: source,
-						)
+									comments: comments_for(node),
+									parent: parent,
+									node: node,
+									language: @language,
+									visibility: @visibility,
+									source: source,
+								)
 						
 						yield definition
 					when :if_node
@@ -286,13 +308,15 @@ module Decode
 				end
 				
 				# Extract segments from the given input file.
+				# @parameter source [Source] The source file to parse.
+				# @returns [Enumerator[Segment]] An enumerator of segments.
 				def segments_for(source, &block)
 					result = self.parse_source(source)
 					comments = result.comments.reject do |comment|
 						comment.location.slice.start_with?("#!/") || 
-						comment.location.slice.start_with?("# frozen_string_literal:") ||
-						comment.location.slice.start_with?("# Released under the MIT License.") ||
-						comment.location.slice.start_with?("# Copyright,")
+								comment.location.slice.start_with?("# frozen_string_literal:") ||
+								comment.location.slice.start_with?("# Released under the MIT License.") ||
+								comment.location.slice.start_with?("# Copyright,")
 					end
 					
 					# Now we iterate over the syntax tree and generate segments:
@@ -304,14 +328,16 @@ module Decode
 				# Extract clean comment text from a node by removing leading # symbols and whitespace.
 				# Only returns comments that directly precede the node (i.e., are adjacent to it).
 				# @parameter node [Node] The AST node with comments.
-				# @returns [Array] Array of cleaned comment strings.
+				# Extract comments that directly precede a node.
+				# @parameter node [untyped] The syntax tree node.
+				# @returns [Array[String]] Array of cleaned comment strings.
 				def comments_for(node)
 					# Find the node's starting line
 					node_start_line = node.location.start_line
 					
 					# Filter comments to only include those that directly precede the node
 					# We work backwards from the line before the node to find consecutive comments
-					adjacent_comments = []
+					adjacent_comments = [] #: Array[String]
 					expected_line = node_start_line - 1
 					
 					# Process comments in reverse order to work backwards from the node
@@ -337,16 +363,31 @@ module Decode
 					end
 				end
 				
+				# Assign a definition to a parent scope.
+				# @parameter parent [Definition?] The parent definition.
+				# @parameter definition [Definition] The definition to assign.
 				def assign_definition(parent, definition)
-					(@definitions[parent] ||= {})[definition.name] = definition
+					parent_definitions = @definitions[parent] ||= {}
+					parent_definitions[definition.name] = definition
 				end
 				
+				# Look up a definition in the parent scope.
+				# @parameter parent [Definition?] The parent definition.
+				# @parameter name [Symbol] The definition name to look up.
+				# @returns [Definition?] The found definition, if any.
 				def lookup_definition(parent, name)
-					(@definitions[parent] ||= {})[name]
+					if parent_definitions = @definitions[parent]
+						return parent_definitions[name]
+					end
 				end
 				
+				# Store a definition in the parent scope.
+				# @parameter parent [Definition?] The parent definition.
+				# @parameter name [Symbol] The definition name.
+				# @parameter definition [Definition] The definition to store.
 				def store_definition(parent, name, definition)
-					(@definitions[parent] ||= {})[name] = definition
+					parent_definitions = @definitions[parent] ||= {}
+					parent_definitions[name] = definition
 				end
 				
 				# Parse the given source object, can be a string or a Source instance.
@@ -363,8 +404,8 @@ module Decode
 					saved_visibility = @visibility
 					@visibility = visibility
 					yield
-				ensure
-					@visibility = saved_visibility
+						ensure
+							@visibility = saved_visibility
 				end
 				
 				NAME_ATTRIBUTE = /\A@name\s+(?<value>.*?)\Z/
@@ -441,9 +482,9 @@ module Decode
 				end
 				
 				KIND_ATTRIBUTE = /\A
-					(@(?<kind>attribute)\s+(?<value>.*?))|
-					(@define\s+(?<kind>)\s+(?<value>.*?))
-				\Z/x
+							(@(?<kind>attribute)\s+(?<value>.*?))|
+							(@define\s+(?<kind>)\s+(?<value>.*?))
+						\Z/x
 				
 				def kind_for(node, comments = nil)
 					comments&.each do |comment|
@@ -456,8 +497,8 @@ module Decode
 				end
 				
 				SCOPE_ATTRIBUTE = /\A
-					@scope\s+(?<names>.*?)
-				\Z/x
+							@scope\s+(?<names>.*?)
+						\Z/x
 				
 				def scope_for(comments, parent = nil, &block)
 					comments&.each do |comment|
@@ -509,20 +550,20 @@ module Decode
 								# Start a new segment with these comments
 								yield current_segment if current_segment
 								current_segment = Segment.new(
-									preceding_comments.map{|comment| comment.location.slice.sub(/^#[\s\t]?/, "")},
-									@language,
-									statement
-								)
+											preceding_comments.map{|comment| comment.location.slice.sub(/^#[\s\t]?/, "")},
+											@language,
+											statement
+										)
 							elsif current_segment
 								# Extend current segment with this statement
 								current_segment.expand(statement)
 							else
 								# Start a new segment without comments
 								current_segment = Segment.new(
-									[],
-									@language,
-									statement
-								)
+											[],
+											@language,
+											statement
+										)
 							end
 						end
 						
@@ -530,10 +571,10 @@ module Decode
 					else
 						# One top level segment:
 						segment = Segment.new(
-							[],
-							@language,
-							node
-						)
+									[],
+									@language,
+									node
+								)
 						
 						yield segment
 					end

data/lib/decode/language/ruby/reference.rb

@@ -12,7 +12,8 @@ module Decode
 			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.
+				# @returns [Reference] A new reference instance.
 				def self.from_const(node, language)
 					lexical_path = append_const(node)
 					
@@ -22,6 +23,7 @@ module Decode
 				# 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
@@ -50,6 +52,7 @@ module Decode
 				
 				# Split a Ruby identifier into prefix and name components.
 				# @parameter text [String] The text to split.
+				# @returns [Array] Array of prefix and name pairs.
 				def split(text)
 					text.scan(/(::|\.|#|:)?([^:.#]+)/)
 				end

data/lib/decode/language/ruby/segment.rb

@@ -12,7 +12,7 @@ module Decode
 			class Segment < Decode::Segment
 				# Initialize a new Ruby segment.
 				# @parameter comments [Array(String)] The comments for this segment.
-				# @parameter language [Language] The language instance.
+				# @parameter language [Generic] The language instance.
 				# @parameter node [Prism::Node] The syntax tree node.
 				# @parameter options [Hash] Additional options.
 				def initialize(comments, language, node, **options)
@@ -32,7 +32,7 @@ module Decode
 				end
 				
 				# The source code trailing the comments.
-				# @returns [String | Nil]
+				# @returns [String?]
 				def code
 					@expression.slice
 				end

data/lib/decode/languages.rb

@@ -23,6 +23,12 @@ module Decode
 			@extensions = {}
 		end
 		
+		# @attribute [Hash[String, Language::Generic]] The named languages.
+		attr :named
+		
+		# @attribute [Hash[String, Language::Generic]] The languages by extension.
+		attr :extensions
+		
 		# Freeze the languages context to prevent further modifications.
 		def freeze
 			return unless frozen?
@@ -35,6 +41,7 @@ module Decode
 		
 		# Add a language to this context.
 		# @parameter language [Language::Generic] The language to add.
+		# @returns [self]
 		def add(language)
 			# Register by name:
 			language.names.each do |name|
@@ -45,22 +52,26 @@ module Decode
 			language.extensions.each do |extension|
 				@extensions[extension] = language
 			end
+			
+			return self
 		end
 		
 		# Fetch a language by name, creating a generic language if needed.
 		# @parameter name [String] The name of the language to fetch.
-		# @returns [Language::Generic] The language instance for the given name.
+		# @returns [Language::Generic?] The language instance for the given name, or nil if frozen and not found.
 		def fetch(name)
 			@named.fetch(name) do
 				unless @named.frozen?
 					@named[name] = Language::Generic.new(name)
+				else
+					nil
 				end
 			end
 		end
 		
 		# Create a source object for the given file path.
 		# @parameter path [String] The file system path to create a source for.
-		# @returns [Source | Nil] A source object if the file extension is supported, nil otherwise.
+		# @returns [Source?] A source object if the file extension is supported, nil otherwise.
 		def source_for(path)
 			extension = File.extname(path)
 			
@@ -69,17 +80,27 @@ module Decode
 			end
 		end
 		
+		# @constant [Regexp] Regular expression for parsing language references.
 		REFERENCE = /\A(?<name>[a-z]+)?\s+(?<identifier>.*?)\z/
 		
 		# Parse a language agnostic reference.
 		# @parameter text [String] The text to parse (e.g., "ruby MyModule::MyClass").
-		# @parameter default_language [Language::Generic] The default language to use if none specified.
-		# @returns [Language::Reference | Nil] The parsed reference, or nil if parsing fails.
+		# @parameter default_language [Language::Generic?] The default language to use if none specified.
+		# @returns [Language::Reference?] The parsed reference, or nil if parsing fails.
 		def parse_reference(text, default_language: nil)
 			if match = REFERENCE.match(text)
-				language = self.fetch(match[:name]) || default_language
+				name = match[:name]
+				identifier = match[:identifier]
 				
-				return language.reference_for(match[:identifier])
+				if name
+					language = self.fetch(name) || default_language
+				else
+					language = default_language
+				end
+				
+				if language && identifier
+					return language.reference_for(identifier)
+				end
 			elsif default_language
 				return default_language.reference_for(text)
 			end
@@ -88,9 +109,9 @@ module Decode
 		# Create a reference for the given language and identifier.
 		# @parameter name [String] The name of the language.
 		# @parameter identifier [String] The identifier to create a reference for.
-		# @returns [Language::Reference] The created reference.
+		# @returns [Language::Reference?] The created reference, or nil if language not found.
 		def reference_for(name, identifier)
-			self.fetch(name).reference_for(identifier)
+			self.fetch(name)&.reference_for(identifier)
 		end
 	end
 end

data/lib/decode/location.rb

@@ -5,7 +5,18 @@
 
 module Decode
 	# Represents a location in a source file.
-	class Location < Struct.new(:path, :line)
+	class Location
+		def initialize(path, line)
+			@path = path
+			@line = line
+		end
+		
+		# @attribute [String] The path to the source file.
+		attr :path
+		
+		# @attribute [Integer] The line number in the source file.
+		attr :line
+		
 		# Generate a string representation of the location.
 		def to_s
 			"#{path}:#{line}"