decode 0.26.0 → 0.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 453b1f28ebb358dd7f37f17d12e6e48616895970d0a9a9225ddb8d3384f2fc90
-  data.tar.gz: 3720af135885d5d002f91a3bc758a3f04e58c1d7022fc4d90b008754568b66d2
+  metadata.gz: 65f2a545a291a4258d019ea79ea9c4cda2e4e15af778670b505ac7652d620ee3
+  data.tar.gz: fa7d2328a1eba99917c23de03569575642ae587dbc049ab4a409d84e85824c57
 SHA512:
-  metadata.gz: cf74b8ffc88195be9440a81aeceb0da5b2b77ff9c2e45df2961f683b27ed15f1d5ccab54d161f05931d2c9c5fdd5641b50b6122757b91d55d3a5668c8dcbde1a
-  data.tar.gz: 417e14f2501bdb368a25f5872915d4d3de47cd57f39164977c4a42b372ab41f4a9d4d435644972297f076c84cc3d475f732a4d90677ba0bb7b01e897586ca9b1
+  metadata.gz: 78ac2928c18dc95f78aa181cadca912776e288781ef3f88c0fbd507faae38884d2d66dcf73770dafeb874aff4ef69a2ecec601b6b3e097be02154fe7a06f187b
+  data.tar.gz: acef5f32fcb5b0ff49c076e706555c6eb2fbceed83abc9bd0f35557e72153fcde17fcd6cc31320eb9aee1c71fd73739554d757517b7105f8d080eee8ad71a0dc

data/bake/decode/documentation.rb

@@ -0,0 +1,378 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "fileutils"
+
+def initialize(...)
+	super
+	
+	require "decode/index"
+	require "yaml"
+end
+
+# Generate Markdown documentation for LLM consumption.
+# @parameter root [String] The root path to index (e.g., 'lib').
+# @parameter output_root [String] The root output directory (e.g., 'context').
+# @parameter name [String] The subdirectory name for the generated files (e.g., 'interface').
+def markdown(root, output_root: "context", name: "interface")
+	index = Decode::Index.for(root)
+	
+	# Construct full output directory path
+	output_directory = File.join(output_root, name)
+	
+	# Track all generated files for index.yaml
+	generated_files = []
+	
+	# Group definitions by container (class/module)
+	containers = {}
+	
+	# First pass: collect all definitions
+	index.definitions.each do |qualified_name, definition|
+		# Skip non-public definitions
+		next unless definition.public?
+		
+		# If this is a container, register it
+		if definition.container?
+			containers[qualified_name] ||= {
+				definition: definition,
+				methods: [],
+				aliases: []
+			}
+		else
+			# This is a method/attribute - add to parent container
+			if parent = definition.parent
+				# Find the containing class/module
+				container_definition = parent
+				while container_definition && !container_definition.container?
+					container_definition = container_definition.parent
+				end
+				
+				if container_definition
+					container_name = container_definition.qualified_name
+					containers[container_name] ||= {
+						definition: container_definition,
+						methods: [],
+						aliases: []
+					}
+					if definition.respond_to?(:alias?) && definition.alias?
+						containers[container_name][:aliases] << definition
+					else
+						containers[container_name][:methods] << definition
+					end
+				end
+			end
+		end
+	end
+	
+	$stderr.puts "Found #{containers.size} containers to document"
+	
+	# Generate markdown files for each container
+	containers.each do |qualified_name, data|
+		container = data[:definition]
+		# Preserve original code order as collected by the parser/index:
+		methods = data[:methods]
+		aliases = data[:aliases]
+		
+		# Generate file path
+		file_path = File.join(output_directory, "#{qualified_name.gsub('::', '/')}.md")
+		FileUtils.mkdir_p(File.dirname(file_path))
+		
+		# Generate markdown content
+		content = generate_container_markdown(container, methods, aliases)
+		
+		File.write(file_path, content)
+		generated_files << {
+			path: file_path,
+			qualified_name: qualified_name,
+			kind: container.respond_to?(:container?) && container.container? ? "class/module" : "class/module"
+		}
+		
+		$stderr.puts "Generated: #{file_path}"
+	end
+	
+	$stderr.puts "Generated #{generated_files.size} files in #{output_directory}"
+	
+	# Generate overview/index file
+	overview_path = File.join(output_root, "#{name}.md")
+	overview_content = generate_overview(name, containers, index)
+	File.write(overview_path, overview_content)
+	$stderr.puts "Generated overview: #{overview_path}"
+end
+
+private
+
+# Generate markdown content for a container (class/module) and its methods.
+# @parameter container [Decode::Definition]
+# @parameter methods [Array]
+# @parameter aliases [Array[Decode::Language::Ruby::Alias]]
+def generate_container_markdown(container, methods, aliases)
+	lines = []
+	
+	# Title
+	lines << "# #{container.qualified_name}"
+	lines << ""
+	
+	# Summary from documentation
+	if documentation = container.documentation
+		if summary = extract_summary(documentation)
+			lines << summary
+			lines << ""
+		end
+	end
+	
+	# Metadata
+	kind = case container
+	when Decode::Language::Ruby::Class
+		"Class"
+	when Decode::Language::Ruby::Module
+		"Module"
+	when Decode::Language::Ruby::Singleton
+		"Singleton"
+	else
+		"Container"
+	end
+	
+	meta_lines = ["- Kind: #{kind}"]
+	if container.respond_to?(:super_class) && container.super_class
+		meta_lines << "- Superclass: #{container.super_class}"
+	end
+	if container.respond_to?(:includes) && container.includes.any?
+		meta_lines << "- Includes: #{container.includes.join(', ')}"
+	end
+	if container.respond_to?(:extends) && container.extends.any?
+		meta_lines << "- Extends: #{container.extends.join(', ')}"
+	end
+	if container.respond_to?(:prepends) && container.prepends.any?
+		meta_lines << "- Prepends: #{container.prepends.join(', ')}"
+	end
+	if container.parent
+		meta_lines << "- Namespace: #{container.parent.qualified_name}"
+	end
+	
+	if meta_lines.any?
+		lines << "## Metadata"
+		lines << ""
+		lines.concat(meta_lines)
+		lines << ""
+	end
+	
+	# Description
+	if documentation = container.documentation
+		if description = extract_description(documentation)
+			lines << "## Overview"
+			lines << ""
+			lines << description
+			lines << ""
+		end
+	end	# Attributes
+	attributes = methods.select{|m| m.is_a?(Decode::Language::Ruby::Attribute) rescue false}
+	if attributes.any?
+		lines << "## Attributes"
+		lines << ""
+		attributes.each do |attribute|
+			lines.concat(generate_method_section(attribute))
+		end
+	end
+	
+	# Methods
+	non_attributes = methods.reject{|m| m.is_a?(Decode::Language::Ruby::Attribute) rescue false}
+	if non_attributes.any?
+		lines << "## Methods"
+		lines << ""
+		non_attributes.each do |method|
+			lines.concat(generate_method_section(method, aliases))
+		end
+	end
+	
+	lines.join("\n")
+end
+
+# Generate markdown for a single method.
+# Also annotates any alias names that refer to this method within the same container.
+def generate_method_section(method, aliases = [])
+	lines = []
+	
+	# Method heading
+	lines << "### `#{method.nested_name}`"
+	lines << ""
+	
+	# Also known as (aliases pointing to this method)
+	if aliases && !aliases.empty?
+		alias_names = aliases.select{|a| a.old_name == method.name}.map(&:name)
+		if alias_names.any?
+			lines << "_Also known as:_ #{alias_names.map{|n| "`#{n}`"}.join(", ")}"
+			lines << ""
+		end
+	end
+	
+	# Summary
+	if documentation = method.documentation
+		if summary = extract_summary(documentation)
+			lines << summary
+			lines << ""
+		end
+	end
+	
+	# Signature
+	if signature = method.long_form
+		lines << "**Signature:**"
+		lines << "```ruby"
+		lines << signature
+		lines << "```"
+		lines << ""
+	end
+	
+	# Parameters
+	if documentation = method.documentation
+		parameters = documentation.filter(Decode::Comment::Parameter).to_a
+		if parameters.any?
+			lines << "**Parameters:**"
+			parameters.each do |parameter|
+				parameter_text = "- `#{parameter.name}` `#{parameter.type}`"
+				if description = parameter.text&.join(" ")
+					parameter_text << " — #{description}"
+				end
+				lines << parameter_text
+			end
+			lines << ""
+		end
+		
+		# Returns
+		returns = documentation.filter(Decode::Comment::Returns).to_a
+		if returns.any?
+			lines << "**Returns:**"
+			returns.each do |return_tag|
+				return_text = "- `#{return_tag.type}`"
+				if description = return_tag.text&.join(" ")
+					return_text << " — #{description}"
+				end
+				lines << return_text
+			end
+			lines << ""
+		end
+		
+		# Yields
+		yields_tags = documentation.filter(Decode::Comment::Yields).to_a
+		if yields_tags.any?
+			lines << "**Yields:**"
+			yields_tags.each do |yields_tag|
+				yield_text = "- `#{yields_tag.block}`"
+				if description = yields_tag.text&.join(" ")
+					yield_text << " — #{description}"
+				end
+				lines << yield_text
+			end
+			lines << ""
+		end
+		
+		# Examples
+		examples = documentation.filter(Decode::Comment::Example).to_a
+		if examples.any?
+			examples.each do |example|
+				title = example.title || "Example"
+				lines << "**#{title}:**"
+				lines << "```ruby"
+				lines << example.code if example.code
+				lines << "```"
+				lines << ""
+			end
+		end
+		
+		# Description (longer text after summary)
+		if description = extract_description(documentation)
+			lines << "**Details:**"
+			lines << ""
+			lines << description
+			lines << ""
+		end
+	end
+	
+	lines
+end
+
+# Extract summary (first paragraph) from documentation.
+def extract_summary(documentation)
+	return nil unless documentation.text
+	
+	lines = documentation.text
+	summary_lines = []
+	
+	lines.each do |line|
+		line_str = line.to_s.strip
+		break if line_str.empty? && summary_lines.any?
+		summary_lines << line_str unless line_str.empty?
+	end
+	
+	return nil if summary_lines.empty?
+	summary_lines.join(" ")
+end
+
+# Extract description (everything after summary) from documentation.
+def extract_description(documentation)
+	return nil unless documentation.text
+	
+	lines = documentation.text
+	description_lines = []
+	found_gap = false
+	
+	lines.each do |line|
+		line_str = line.to_s
+		if line_str.strip.empty?
+			found_gap = true if description_lines.any?
+		elsif found_gap
+			description_lines << line_str
+		end
+	end
+	
+	return nil if description_lines.empty?
+	description_lines.join("\n")
+end
+
+# Generate an overview/index file for the documentation.
+def generate_overview(name, containers, index)
+	lines = []
+	
+	lines << "# #{name.capitalize}"
+	lines << ""
+	lines << "This directory contains documentation for all public classes and modules."
+	lines << ""
+	
+	# Group by top-level namespace
+	namespaces = {}
+	containers.each do |qualified_name, data|
+		parts = qualified_name.split("::")
+		top_level = parts.first
+		namespaces[top_level] ||= []
+		namespaces[top_level] << {name: qualified_name, definition: data[:definition]}
+	end
+	
+	lines << "## Namespaces"
+	lines << ""
+	
+	namespaces.keys.sort.each do |namespace|
+		items = namespaces[namespace].sort_by{|item| item[:name]}
+		
+		lines << "### #{namespace}"
+		lines << ""
+		
+		items.each do |item|
+			definition = item[:definition]
+			relative_path = "#{name}/#{item[:name].gsub('::', '/')}.md"
+			
+			if documentation = definition.documentation
+				if summary = extract_summary(documentation)
+					lines << "- [#{item[:name]}](#{relative_path}) - #{summary}"
+					next
+				end
+			end
+			
+			lines << "- [#{item[:name]}](#{relative_path})"
+		end
+		
+		lines << ""
+	end
+	
+	lines.join("\n")
+end

data/context/documentation-coverage.md

@@ -60,7 +60,7 @@ A definition is considered documented if it has:
 - A `@namespace` pragma (for organizational modules).
 
 ```ruby
-# Represents a user in the system.
+# A user in the system.
 class MyClass
 end
 
@@ -130,7 +130,7 @@ Returns true if authentication is successful.
 ### Document all public APIs
 
 ```ruby
-# Represents a user management system.
+# A user account with authentication and email.
 class User
 	# @attribute [String] The user's email address.
 	attr_reader :email
@@ -197,7 +197,7 @@ Solution: Add description and pragmas:
 # @returns [Array] Processed results.
 def process_data(data)
 	# Process the input:
-	results = data.map {|item| transform(item)}
+	results = data.map{|item| transform(item)}
 	
 	# Return processed results:
 	results

data/context/ruby-documentation.md

@@ -9,7 +9,9 @@ This guide covers documentation practices and pragmas supported by the Decode ge
 #### Definition Documentation
 
 - Full sentences: All documentation for definitions (classes, modules, methods) should be written as complete sentences with proper grammar and punctuation.
-- Class documentation: Documentation for classes should generally start with "Represents a ..." to clearly indicate what the class models or encapsulates.
+- Class documentation: Should directly describe what the class *is* or *does*.
+	- For data/model classes, "A user account in the system." works well.
+	- For functional classes (servers, clients, connections), lead with what the class does: "An HTTP client that manages persistent connections...".
 - Method documentation: Should clearly describe what the method does, not how it does it.
 - Markdown format: All documentation comments are written in Markdown format, allowing for rich formatting including lists, emphasis, code blocks, and links.
 
@@ -32,8 +34,12 @@ This guide covers documentation practices and pragmas supported by the Decode ge
 
 #### Examples
 
+##### Data/Model Classes
+
+For classes that model domain concepts, describe what the class is:
+
 ```ruby
-# Represents a user account in the system.
+# A user account in the system.
 class User
 	# @attribute [String] The user's email address.
 	attr_reader :email
@@ -70,26 +76,35 @@ class User
 		true
 	end
 end
+```
 
-# Represents a collection of users with search capabilities.
-class UserCollection
-	# Find users matching the given criteria.
-	# @parameter criteria [Hash] Search parameters.
-	# @returns [Array(User)] Matching users.
-	def find(**criteria)
-		# Start with all users:
-		results = @users.dup
-		
-		# Apply each filter criterion:
-		criteria.each do |key, value|
-			results = filter_by(results, key, value)
-		end
-		
-		results
+##### Functional/Service Classes
+
+For classes that *do* something (clients, servers, processors), lead with what the class does:
+
+```ruby
+# An HTTP client that manages persistent connections to a remote server, with automatic retries for idempotent requests.
+class Client
+	# Send a request to the remote server.
+	# @parameter request [Protocol::HTTP::Request] The request to send.
+	# @returns [Protocol::HTTP::Response] The response from the server.
+	def call(request)
+		# ...
+	end
+	
+	# Close the client and release all connections.
+	def close
+		# ...
 	end
 end
+
+# Raised when a connection to the remote server cannot be established.
+class ConnectionError < StandardError
+end
 ```
 
+Note the difference: `User` is described as a thing ("A user account..."), while `Client` is described by what it does ("An HTTP client that manages..."), and `ConnectionError` is described by when it occurs ("Raised when...").
+
 **Key formatting examples from above:**
 - `{disable!}` - Creates a link to the `disable!` method (relative reference)
 - `active?` - Formats the method name in monospace (backticks for code formatting)
@@ -155,7 +170,7 @@ Type signatures are used to specify the expected types of parameters, return val
 Documents class attributes, instance variables, and `attr_*` declarations. Prefer to have one attribute per line for clarity.
 
 ```ruby
-# Represents a person with basic attributes.
+# A person with basic attributes.
 class Person
 	# @attribute [String] The person's full name.
 	attr_reader :name

data/lib/decode/definition.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2025, by Samuel Williams.
+# Copyright, 2020-2026, by Samuel Williams.
 
 require_relative "location"
 
@@ -166,6 +166,14 @@ module Decode
 			false
 		end
 		
+		# Whether this definition represents an alias to another definition.
+		# Tools can use this to filter aliases from outputs without parsing text.
+		#
+		# @returns [bool] False by default; specific definition types may override.
+		def alias?
+			false
+		end
+		
 		# Whether this represents a single entity to be documented (along with it's contents).
 		#
 		# @returns [bool]

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 require_relative "definition"
 
@@ -21,6 +21,18 @@ module Decode
 				
 				attr :old_name
 				
+				# Whether this definition represents an alias.
+				# @returns [bool] Always true for aliases.
+				def alias?
+					true
+				end
+				
+				# The original name this alias refers to.
+				# @returns [Symbol]
+				def aliased_name
+					@old_name
+				end
+				
 				# Aliases don't require separate documentation as they reference existing methods.
 				# @returns [bool] Always false for aliases.
 				def coverage_relevant?

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2025, by Samuel Williams.
+# Copyright, 2020-2026, by Samuel Williams.
 
 require_relative "definition"
 
@@ -18,10 +18,23 @@ module Decode
 					super(*arguments, **options)
 					
 					@super_class = super_class
+					@includes = []
+					@extends = []
+					@prepends = []
 				end
 				
+				# @attribute [String?] The super class name.
 				attr :super_class
 				
+				# @attribute [Array(Symbol)] Modules included into this class.
+				attr :includes
+				
+				# @attribute [Array(Symbol)] Modules extended into this class (adds singleton methods).
+				attr :extends
+				
+				# @attribute [Array(Symbol)] Modules prepended into this class (method lookup precedence).
+				attr :prepends
+				
 				# A class is a container for other definitions.
 				def container?
 					true

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2025, by Samuel Williams.
+# Copyright, 2020-2026, by Samuel Williams.
 
 require_relative "definition"
 
@@ -10,6 +10,24 @@ module Decode
 		module Ruby
 			# A Ruby-specific module.
 			class Module < Definition
+				# Initialize a module with its name and options.
+				def initialize(*arguments, **options)
+					super(*arguments, **options)
+					
+					@includes = []
+					@extends = []
+					@prepends = []
+				end
+				
+				# @attribute [Array(Symbol)] Modules included into this module.
+				attr :includes
+				
+				# @attribute [Array(Symbol)] Modules extended into this module (adds singleton methods).
+				attr :extends
+				
+				# @attribute [Array(Symbol)] Modules prepended into this module (method lookup precedence).
+				attr :prepends
+				
 				# A module is a container for other definitions.
 				def container?
 					true

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2025, by Samuel Williams.
+# Copyright, 2020-2026, by Samuel Williams.
 
 require "prism"
 
@@ -93,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
@@ -114,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
@@ -134,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
 							
@@ -152,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
@@ -176,6 +176,40 @@ module Decode
 						name = node.name
 						
 						case name
+						when :include, :extend, :prepend
+							# Handle mixins inside classes/modules
+							if parent
+								if node.arguments
+									node.arguments.arguments.each do |arg|
+										mod_name = case arg.type
+										when :constant_read_node
+											# Qualify with enclosing namespace if available (e.g. Mixins::Greeting)
+											if parent.parent && parent.parent.respond_to?(:qualified_name)
+												"#{parent.parent.qualified_name}::#{arg.name}"
+											else
+												arg.name.to_s
+											end
+										when :constant_path_node
+											nested_name_for(arg)
+										else
+											# Skip unsupported argument types (e.g., dynamic expressions)
+											nil
+										end
+										if mod_name
+											case name
+											when :include
+												parent.respond_to?(:includes) && parent.includes << mod_name
+											when :extend
+												parent.respond_to?(:extends) && parent.extends << mod_name
+											when :prepend
+												parent.respond_to?(:prepends) && parent.prepends << mod_name
+											end
+										end
+									end
+								end
+							end
+							# Don't treat include/extend as definitions.
+							return
 						when :public, :protected, :private
 							# Handle cases like "private def foo" where method definitions are arguments
 							if node.arguments
@@ -187,13 +221,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
@@ -217,9 +251,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
@@ -233,29 +267,29 @@ 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
 						else
 							# Check if this call should be treated as a definition
 							# either because it has a @name comment, @attribute comment, or a block
-							has_name_comment = comments_for(node).any? {|comment| comment.match(NAME_ATTRIBUTE)}
+							has_name_comment = comments_for(node).any?{|comment| comment.match(NAME_ATTRIBUTE)}
 							has_attribute_comment = kind_for(node, comments_for(node))
 							has_block = node.block
 							
 							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
 								
@@ -265,19 +299,19 @@ module Decode
 								end
 							end
 						end
-					when :alias_method_node
-						# Handle alias new_name old_name syntax
+					when :alias_node, :alias_method_node
+						# Handle `alias new_name old_name` syntax:
 						new_name = node.new_name.unescaped
 						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
@@ -550,20 +584,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
 						
@@ -571,10 +605,10 @@ module Decode
 					else
 						# One top level segment:
 						segment = Segment.new(
-									[],
-									@language,
-									node
-								)
+							[],
+							@language,
+							node
+						)
 						
 						yield segment
 					end

data/lib/decode/rbs/class.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 require "rbs"
 require_relative "wrapper"
@@ -35,6 +35,7 @@ module Decode
 						name: generic.to_sym,
 						variance: nil,
 						upper_bound: nil,
+						lower_bound: nil,
 						location: nil
 					)
 				end
@@ -51,10 +52,10 @@ module Decode
 				# Extract super class if present:
 				super_class = if @definition.super_class
 					::RBS::AST::Declarations::Class::Super.new(
-								name: qualified_name_to_rbs(@definition.super_class),
-								args: [],
-								location: nil
-							)
+						name: qualified_name_to_rbs(@definition.super_class),
+						args: [],
+						location: nil
+					)
 				end
 				
 				# Create the class declaration with generics:

data/lib/decode/rbs/method.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 require "rbs"
 require "console"
@@ -103,15 +103,15 @@ module Decode
 				kind = @definition.receiver ? :singleton : :instance
 				
 				::RBS::AST::Members::MethodDefinition.new(
-				name: method_name.to_sym,
-				kind: kind,
-				overloads: overloads,
-				annotations: [],
-				location: nil,
-				comment: comment,
-				overloading: false,
-				visibility: @definition.visibility || :public
-			)
+					name: method_name.to_sym,
+					kind: kind,
+					overloads: overloads,
+					annotations: [],
+					location: nil,
+					comment: comment,
+					overloading: false,
+					visibility: @definition.visibility || :public
+				)
 			end
 			
 			# Build a complete RBS function type from AST information.
@@ -265,7 +265,7 @@ module Decode
 				
 				# 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)}
+				param_tags = param_tags.reject{|tag| tag.is_a?(Decode::Comment::Option)}
 				return [] if param_tags.empty?
 				
 				param_tags.map do |tag|

data/lib/decode/rbs/module.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 require "rbs"
 require_relative "wrapper"
@@ -62,11 +62,11 @@ module Decode
 					type = ::Decode::RBS::Type.parse(type_string)
 					
 					::RBS::AST::Declarations::Constant.new(
-					name: constant_definition.name.to_sym,
-					type: type,
-					location: nil,
-					comment: nil
-				)
+						name: constant_definition.name.to_sym,
+						type: type,
+						location: nil,
+						comment: nil
+					)
 				end
 			end
 			

data/lib/decode/rbs/type.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 require "rbs"
 require "console"
@@ -21,10 +21,10 @@ module Decode
 					true
 				when ::RBS::Types::Union
 					# Type | nil form - recursively check all union members
-					rbs_type.types.any? {|type| nullable?(type)}
+					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)}
+					rbs_type.types.any?{|type| nullable?(type)}
 				when ::RBS::Types::Bases::Nil
 					# Direct nil type
 					true

data/lib/decode/version.rb

@@ -5,5 +5,5 @@
 
 module Decode
 	# @constant [String] The version of the gem.
-	VERSION = "0.26.0"
+	VERSION = "0.27.0"
 end

data/license.md

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright, 2020-2025, by Samuel Williams.  
+Copyright, 2020-2026, by Samuel Williams.  
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/readme.md

@@ -24,6 +24,10 @@ 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.27.0
+
+    - Add `decode:documentation:markdown` bake task for generating LLM-optimized Markdown documentation.
+
 ### v0.26.0
 
   - Add support for `@example` pragmas in Ruby documentation comments.
@@ -60,6 +64,22 @@ We welcome contributions to this project.
 4.  Push to the branch (`git push origin my-new-feature`).
 5.  Create new Pull Request.
 
+### Running Tests
+
+To run the test suite:
+
+``` shell
+bundle exec sus
+```
+
+### Making Releases
+
+To make a new release:
+
+``` shell
+bundle exec bake gem:release:patch # or minor or major
+```
+
 ### Developer Certificate of Origin
 
 In order to protect users of this project, we require all contributors to comply with the [Developer Certificate of Origin](https://developercertificate.org/). This ensures that all contributions are properly licensed and attributed.

data/releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## v0.27.0
+
+    - Add `decode:documentation:markdown` bake task for generating LLM-optimized Markdown documentation.
+
 ## v0.26.0
 
   - Add support for `@example` pragmas in Ruby documentation comments.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: decode
 version: !ruby/object:Gem::Version
-  version: 0.26.0
+  version: 0.27.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -71,6 +71,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - agent.md
+- bake/decode/documentation.rb
 - bake/decode/index.rb
 - bake/decode/rbs.rb
 - context/documentation-coverage.md
@@ -150,14 +151,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Code analysis for documentation generation.
 test_files: []