decode 0.24.2 → 0.24.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d6a3ca54cbbfe55c6946466efdeef71ee9b103ceb59ab27c313a9e3a4345264b
-  data.tar.gz: 00fe1c5faa769e7daa607cd46a48920ad04b4926493e1b841154d9a5f193b12a
+  metadata.gz: 69a1cefaeaebe1d53746d8244acad208122dccd964ef8ded1c70b7f3e1ab856f
+  data.tar.gz: f3ef222826e20af488964480baf64d72ee9b55a6ad849057f40eebe09934ca37
 SHA512:
-  metadata.gz: 288e3c278877013c633055242d28c1f2097ca38576896f86d486ee56f1ef3e246af36dce75d30c9c364cd65b9d4928b875b0f7d384c485efde3b27cad8658b14
-  data.tar.gz: debf415bab150aaeb345e3013bc6d07896ccf02006e0787eef2ba73754b9c02725007df042e397bedfc02d0b7b8acc266a946535acafcc6d03bd4e069836a937
+  metadata.gz: a2c97db6ff06407597b2c42513a0cb4827824abb41ec480a8e6fb1e2d3b8c4366e61c2d34f1f2f706d3cee33f6be6ff5464ef8e668e491534a9692954d14bba3
+  data.tar.gz: f051d9ea291738263feee8091a40137ca4578316f762b6d93ef26dc03001f1a138d26a25878c39a7029eee4f59a742a2d59492a1b0ac55a77c8312d28de53a86

data/bake/decode/rbs.rb

@@ -13,6 +13,6 @@ end
 # @parameter root [String] The root path to index.
 def generate(root)
 	index = Decode::Index.for(root)
-	generator = Decode::RBS::Generator.new
+	generator = Decode::RBS::Generator.new(include_private: true)
 	generator.generate(index)
 end

data/context/coverage.md

@@ -60,7 +60,7 @@ end
 
 # Process user data and return formatted results.
 # @parameter name [String] The user's name.
-# @returns [Boolean] Success status.
+# @returns [bool] Success status.
 def process(name)
   # Validation logic here:
   return false if name.empty?

data/context/getting-started.md

@@ -71,7 +71,7 @@ source_code = <<~RUBY
     # Initialize a new user.
     # @parameter email [String] The user's email address.
     # @parameter options [Hash] Additional options.
-    # @option :active [Boolean] Whether the account is active.
+    # @option :active [bool] Whether the account is active.
     # @raises [ArgumentError] If email is invalid.
     def initialize(email, options = {})
       # Validate the email format:

data/context/ruby-documentation.md

@@ -51,7 +51,7 @@ class User
 	
 	# Authenticate the user with the provided password.
 	# @parameter password [String] The password to verify.
-	# @returns [Boolean] True if authentication succeeds.
+	# @returns [bool] True if authentication succeeds.
 	def authenticate(password)
 		# Hash the password for comparison:
 		hashed = hash_password(password)
@@ -64,7 +64,7 @@ class User
 	# This method sets the user's status to inactive. Use this instead of
 	# the deprecated {disable!} method. The account status can be checked
 	# using `active?` or by examining the `:active` attribute.
-	# @returns [Boolean] Returns `true` if deactivation was successful.
+	# @returns [bool] Returns `true` if deactivation was successful.
 	def deactivate!
 		@active = false
 		true
@@ -187,7 +187,7 @@ Documents hash options (keyword arguments).
 
 ```ruby
 # @parameter user [User] The user object.
-# @option :cached [Boolean] Whether to cache the result.
+# @option :cached [bool] Whether to cache the result.
 # @option :timeout [Integer] Request timeout in seconds.
 def fetch_user_data(user, **options)
 	# ...

data/context/types.md

@@ -0,0 +1,127 @@
+# 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
+
+### Deploymnet
+
+Make sure `bake-test-types` is added to the `test` group in `gems.rb` (or `Gemfile`).
+
+```ruby
+group :test do
+	# ...
+	gem "bake-test"
+	gem "bake-test-external"
+	gem "bake-test-types"
+	# ...
+end
+```
+
+Then, create `.github/workflows/test-types.yaml`:
+
+```yaml
+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 bake test:types
+```

data/lib/decode/comment/attribute.rb

@@ -13,13 +13,16 @@ module Decode
 		# - `@attribute [Integer] The person's age.`
 		#
 		class Attribute < Tag
-			PATTERN = /\A\[(?<type>.*?)\](\s+(?<details>.*?))?\Z/
+			# @constant [Regexp] Pattern for matching attribute declarations.
+			PATTERN = /\A\[#{Tag.bracketed_content(:type)}\](\s+(?<details>.*?))?\Z/
 			
 			# Build an attribute from a directive and match.
 			# @parameter directive [String] The original directive text.
 			# @parameter match [MatchData] The regex match data.
 			def self.build(directive, match)
-				node = self.new(directive, match[:type])
+				type = match[:type] or raise "Missing type in attribute match!"
+				
+				node = self.new(directive, type)
 				
 				if details = match[:details]
 					node.add(Text.new(details))

data/lib/decode/comment/constant.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "tag"
+require_relative "text"
+
+module Decode
+	module Comment
+		# Represents a constant type declaration.
+		#
+		# - `@constant [Regexp] Pattern for matching parameters.`
+		#
+		class Constant < Tag
+			# @constant [Regexp] Pattern for matching constant declarations.
+			PATTERN = /\A\[#{Tag.bracketed_content(:type)}\](\s+(?<details>.*?))?\Z/
+			
+			# Build a constant from a directive and regex match.
+			# @parameter directive [String] The original directive text.
+			# @parameter match [MatchData] The regex match data containing type and details.
+			# @returns [Constant] A new constant object.
+			def self.build(directive, match)
+				type = match[:type] or raise "Missing type in constant match!"
+				
+				node = self.new(directive, type)
+				
+				if details = match[:details]
+					node.add(Text.new(details))
+				end
+				
+				return node
+			end
+			
+			# Initialize a new constant.
+			# @parameter directive [String] The directive that generated the tag.
+			# @parameter type [String] The type of the constant.
+			def initialize(directive, type)
+				super(directive)
+				@type = type
+			end
+			
+			# @attribute [String] The type of the constant.
+			attr :type
+		end
+	end
+end 

data/lib/decode/comment/node.rb

@@ -8,49 +8,67 @@ module Decode
 		# Represents a node in a comment tree structure.
 		class Node
 			# Initialize the node.
-			# @parameter children [Array(Node) | Nil]
-			def initialize(children = nil)
+			# @parameter children [Array(Node | Text)?] The initial children array containing both structured nodes and text content.
+			def initialize(children)
 				@children = children
 			end
 			
 			# Whether this node has any children nodes.
 			# Ignores {Text} instances.
-			# @returns [Boolean]
+			# @returns [bool]
 			def children?
-				@children&.any?{|child| child.is_a?(Node)}
+				@children&.any?{|child| child.is_a?(Node)} || false
 			end
 			
 			# Add a child node to this node.
-			# @parameter child [Node] The node to add.
+			# @parameter child [Node | Text] The node to add.
 			def add(child)
-				@children ||= []
-				@children << child
+				if children = @children
+					children << child
+				else
+					@children = [child]
+				end
+				
+				return self
 			end
 			
-			# @attribute [Array(Node | Text) | Nil] Any children of this node.
+			# Contains a mix of Node objects (structured comment tags like `@parameter`, `@returns`) and Text objects (plain comment text and tag descriptions).
+			# @attribute [Array(Node | Text)?] The children of this node.
 			attr :children
 			
 			# Enumerate all non-text children nodes.
+			# @yields {|node| process each node}
+			# 	@parameter node [Node] A structured child node (Text nodes are filtered out).
+			# @returns [Enumerator(Node)] Returns an enumerator if no block given.
+			# @returns [self] Otherwise returns self.
 			def each(&block)
 				return to_enum unless block_given?
 				
 				@children&.each do |child|
 					yield child if child.is_a?(Node)
 				end
+				
+				return self
 			end
 			
 			# Filter children nodes by class type.
 			# @parameter klass [Class] The class to filter by.
+			# @yields {|node| process each filtered node}
+			# 	@parameter node [Object] A child node that is an instance of klass.
+			# @returns [Enumerator(Node)] Returns an enumerator if no block given.
+			# @returns [self] Otherwise returns self.
 			def filter(klass)
 				return to_enum(:filter, klass) unless block_given?
 				
 				@children&.each do |child|
 					yield child if child.is_a?(klass)
 				end
+				
+				return self
 			end
 			
 			# Any lines of text associated with this node.
-			# @returns [Array(String) | Nil] The lines of text.
+			# @returns [Array(String)?] The lines of text.
 			def text
 				if text = self.extract_text
 					return text if text.any?
@@ -70,11 +88,13 @@ module Decode
 			
 			protected
 			
+			# Extract text lines from Text children of this node.
+			# @returns [Array(String)?] Array of text lines, or nil if no children.
 			def extract_text
 				if children = @children
-					@children.select{|child| child.kind_of?(Text)}.map(&:line)
-				else
-					nil
+					children.filter_map do |child|
+						child.line if child.is_a?(Text)
+					end
 				end
 			end
 		end

data/lib/decode/comment/option.rb

@@ -9,7 +9,7 @@ module Decode
 	module Comment
 		# Describes a method option (keyword argument).
 		#
-		# - `@option :cached [Boolean] Whether to cache the value.`
+		# - `@option :cached [bool] Whether to cache the value.`
 		#
 		class Option < Parameter
 		end

data/lib/decode/comment/parameter.rb

@@ -12,14 +12,18 @@ module Decode
 		# - `@parameter age [Float] The users age.`
 		#
 		class Parameter < Tag
-			PATTERN = /\A(?<name>.*?)\s+\[(?<type>.*?)\](\s+(?<details>.*?))?\Z/
+			# @constant [Regexp] Pattern for matching parameter declarations.
+			PATTERN = /\A(?<name>.*?)\s+\[#{Tag.bracketed_content(:type)}\](\s+(?<details>.*?))?\Z/
 			
 			# Build a parameter from a directive and regex match.
 			# @parameter directive [String] The original directive text.
 			# @parameter match [MatchData] The regex match data containing name, type, and details.
 			# @returns [Parameter] A new parameter object.
 			def self.build(directive, match)
-				node = self.new(directive, match[:name], match[:type])
+				name = match[:name] or raise ArgumentError, "Missing name in parameter match!"
+				type = match[:type] or raise ArgumentError, "Missing type in parameter match!"
+				
+				node = self.new(directive, name, type)
 				
 				if details = match[:details]
 					node.add(Text.new(details))

data/lib/decode/comment/rbs.rb

@@ -34,10 +34,10 @@ module Decode
 			
 			# Initialize a new RBS pragma.
 			# @parameter directive [String] The directive name.
-			# @parameter text [String] The RBS type annotation text.
-			def initialize(directive, text = nil)
+			# @parameter text [String?] The RBS type annotation text.
+			def initialize(directive, text)
 				super(directive)
-				@text = text&.strip
+				@text = text&.strip || ""
 			end
 			
 			# The RBS type annotation text.
@@ -45,13 +45,13 @@ module Decode
 			attr :text
 			
 			# Check if this is a generic type declaration.
-			# @returns [Boolean] True if this is a generic declaration.
+			# @returns [bool] True if this is a generic declaration.
 			def generic?
-				@text&.start_with?("generic ")
+				@text.start_with?("generic ")
 			end
 			
 			# Extract the generic type parameter name.
-			# @returns [String | Nil] The generic type parameter name, or nil if not a generic.
+			# @returns [String?] The generic type parameter name, or nil if not a generic.
 			def generic_parameter
 				if generic?
 					# Extract the parameter name from "generic T" or "generic T, U"
@@ -61,13 +61,13 @@ module Decode
 			end
 			
 			# Check if this is a method type signature.
-			# @returns [Boolean] True if this is a method signature.
+			# @returns [bool] True if this is a method signature.
 			def method_signature?
 				@text && !generic?
 			end
 			
 			# Get the method type signature text.
-			# @returns [String | Nil] The method signature text, or nil if not a method signature.
+			# @returns [String?] The method signature text, or nil if not a method signature.
 			def method_signature
 				method_signature? ? @text : nil
 			end

data/lib/decode/comment/tag.rb

@@ -8,7 +8,26 @@ require_relative "node"
 module Decode
 	module Comment
 		# Represents a documentation tag parsed from a comment directive.
+		# Subclasses should define a PATTERN constant for matching their specific syntax.
 		class Tag < Node
+			# @constant [Regexp] Abstract pattern constant - subclasses must override this.
+			PATTERN = /(?<never_matches_anything>\A\z)/
+			
+			# Abstract method: Build a tag from directive and match data.
+			# Subclasses must implement this method.
+			# @parameter directive [String] The directive that generated the tag.
+			# @parameter match [MatchData] The regex match data.
+			# @returns [Tag] A new tag instance.
+			def self.build(directive, match)
+				raise NotImplementedError, "Subclasses must implement build method"
+			end
+			# Build a pattern for bracketed content, supporting nested brackets.
+			# @parameter name [Symbol] The name of the group.
+			# @returns [String] The pattern.
+			def self.bracketed_content(name)
+				"(?<#{name}>(?:[^\\[\\]]+|\\[\\g<#{name}>\\])*)"
+			end
+			
 			# Match text against the tag pattern.
 			# @parameter text [String] The text to match.
 			def self.match(text)

data/lib/decode/comment/tags.rb

@@ -10,7 +10,10 @@ module Decode
 		# Represents a collection of documentation tags and their parsing logic.
 		class Tags
 			# Build a tags parser with directive mappings.
-			# @parameter block [Proc] A block that yields the directives hash.
+			# @yields {|directives| directives['directive'] = Class}
+			# 	@parameter directives [Hash(String, _Directive)] The directive mappings hash to configure.
+			# @returns [Tags] A new tags parser with the configured directives.
+			# @rbs () { (Hash[String, Class]) -> void } -> Tags
 			def self.build
 				directives = Hash.new
 				
@@ -20,7 +23,7 @@ module Decode
 			end
 			
 			# Initialize a new tags parser.
-			# @parameter directives [Hash(String, Class)] The directive mappings.
+			# @parameter directives [Hash(String, _Directive)] The directive mappings.
 			def initialize(directives)
 				@directives = directives
 			end
@@ -32,12 +35,16 @@ module Decode
 				line.start_with?("  " * level) || line.start_with?("\t" * level)
 			end
 			
+			# @constant [Regexp] Pattern for matching tag directives in comment lines.
 			PATTERN = /\A\s*@(?<directive>.*?)(\s+(?<remainder>.*?))?\Z/
 			
 			# Parse documentation tags from lines.
 			# @parameter lines [Array(String)] The lines to parse.
 			# @parameter level [Integer] The indentation level.
-			# @parameter block [Proc] A block to yield parsed tags to.
+			# @yields {|node| process parsed node}
+			# 	@parameter node [Node | Text] The parsed node (either a structured tag or plain text).
+			# @returns [void] Parses tags from lines and yields them to the block.
+			# @rbs (Array[String] lines, ?Integer level) { (Node | Text) -> void } -> void
 			def parse(lines, level = 0, &block)
 				while line = lines.first
 					# Is it at the right indentation level:
@@ -48,9 +55,13 @@ module Decode
 					
 					# Match it against a tag:
 					if match = PATTERN.match(line)
-						if klass = @directives[match[:directive]]
+						directive = match[:directive] #: String
+						remainder = match[:remainder] #: String
+						
+						# @type var klass: _Directive?
+						if klass = @directives[directive]
 							yield klass.parse(
-								match[:directive], match[:remainder],
+								directive, remainder,
 								lines, self, level
 							)
 						else

data/lib/decode/comment/text.rb

@@ -15,6 +15,7 @@ module Decode
 				@line = line
 			end
 			
+			# @attribute [String] The text content.
 			attr :line
 			
 			# Traverse the text node.

data/lib/decode/comment/yields.rb

@@ -13,13 +13,16 @@ module Decode
 		#
 		# Should contain nested parameters.
 		class Yields < Tag
+			# @constant [Regexp] Pattern for matching yields declarations.
 			PATTERN = /\A(?<block>{.*?})(\s+(?<details>.*?))?\Z/
 			
 			# Build a yields tag from a directive and match.
 			# @parameter directive [String] The directive name.
 			# @parameter match [MatchData] The regex match data.
 			def self.build(directive, match)
-				node = self.new(directive, match[:block])
+				block = match[:block] or raise "Missing block in yields match!"
+				
+				node = self.new(directive, block)
 				
 				if details = match[:details]
 					node.add(Text.new(details))
@@ -34,6 +37,7 @@ module Decode
 			def initialize(directive, block)
 				super(directive)
 				
+				# @type ivar @block: String?
 				@block = block
 			end