decode 0.25.0 → 0.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01244e4f44a9916295cace389ef8ad2116277a1e5831f500d1e13d953290386a
-  data.tar.gz: e3a85a7b3c2c4d98aa8acc50026a2b515bc33db95fff2ec82c117cda0c1ded52
+  metadata.gz: 65f2a545a291a4258d019ea79ea9c4cda2e4e15af778670b505ac7652d620ee3
+  data.tar.gz: fa7d2328a1eba99917c23de03569575642ae587dbc049ab4a409d84e85824c57
 SHA512:
-  metadata.gz: 974b45b31551d81b281fe5a483a93e0b3ed07a3b6508dbd30df014b45cc2b47a51a34ae6f20454bd973ec7fe5c23393a7176c20028e6dba9a1402fb987c79eb2
-  data.tar.gz: 5028c457dc3c24d79996170725604fddffc127f96a96f8fdf5c3c4188162097538cb103be51808d125e3ed3edec786104874123197bd6e37bd8e463fcf7319b5
+  metadata.gz: 78ac2928c18dc95f78aa181cadca912776e288781ef3f88c0fbd507faae38884d2d66dcf73770dafeb874aff4ef69a2ecec601b6b3e097be02154fe7a06f187b
+  data.tar.gz: acef5f32fcb5b0ff49c076e706555c6eb2fbceed83abc9bd0f35557e72153fcde17fcd6cc31320eb9aee1c71fd73739554d757517b7105f8d080eee8ad71a0dc

checksums.yaml.gz.sig

@@ -1 +1 @@
-7��w1y��.��\��4Jԝ�4�%[kihL!j�4@
g\�JͨȨ�V$N�&�XBd�K#���u���Noz�
+Y��ʇ�7MI��t�s�5�/����E
B��R�t�� HX��D�bR��a��P������“�[��G�A~H����k��ZEk���!�$D����uJC��wH�k�y��p�_T�#�5G+�e_T���ԍ�uT�z�N��xZ`{y�~��25�G&�r�F�Jh�g�0��P���=6�
��5��l����zV�d�޼Y���&��ft��s�#?��� d�.�Lև���qD�8<=0F!T`Q�a��\���/L�pM���Yד*&�9��b�	NԜ����RH��+	߸#o�,5a�ކ.YN��_!���U�PxM@y��N?!}3�Fz�펋��I/u��)��"6������S�@�p�u��x�`1��N�

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

@@ -0,0 +1,254 @@
+# Documentation Coverage
+
+This guide explains how to test and monitor documentation coverage in your Ruby projects using the Decode gem's built-in bake tasks.
+
+## Available Bake Tasks
+
+The Decode gem provides several bake tasks for analyzing your codebase:
+
+- `bake decode:index:coverage` - Check documentation coverage.
+- `bake decode:index:symbols` - List all symbols in the codebase.
+- `bake decode:index:documentation` - Extract all documentation.
+
+## Checking Documentation Coverage
+
+### Basic Coverage Check
+
+```bash
+# Check coverage for the lib directory:
+bake decode:index:coverage lib
+
+# Check coverage for a specific directory:
+bake decode:index:coverage app/models
+```
+
+### Example Output
+
+When you run the coverage command, you'll see output like:
+
+```
+Decode
+Decode::VERSION
+Decode::Languages.all
+Decode::Languages#initialize
+Decode::Languages#freeze
+Decode::Languages#add
+Decode::Languages#fetch
+Decode::Languages#source_for
+Decode::Languages::REFERENCE
+Decode::Languages#reference_for
+Decode::Source#initialize
+... snip ...
+135/215 definitions have documentation.
+```
+
+Using this tool can show you areas that might require more attention.
+
+### Understanding Coverage Output
+
+The coverage check:
+- **Counts only public definitions** (public methods, classes, modules).
+- **Reports the ratio** of documented vs total public definitions.
+- **Lists missing documentation** by qualified name.
+- **Fails with an error** if coverage is incomplete.
+
+### What Counts as "Documented"
+
+A definition is considered documented if it has:
+- Any comment preceding it.
+- Documentation pragmas (like `@parameter`, `@returns`, `@example`).
+- A `@namespace` pragma (for organizational modules).
+
+```ruby
+# A user in the system.
+class MyClass
+end
+
+# @namespace
+module OrganizationalModule
+	# Contains helper functionality.
+end
+
+# Process user data and return formatted results.
+# @parameter name [String] The user's name.
+# @returns [bool] Success status.
+def process(name)
+	# Validation logic here:
+	return false if name.empty?
+	
+	# Processing logic:
+	true
+end
+
+class UndocumentedClass
+end
+```
+
+## Analyzing Symbols
+
+### List All Symbols
+
+```bash
+# See the structure of your codebase
+bake decode:index:symbols lib
+```
+
+This shows the hierarchical structure of your code:
+
+```
+[] -> []
+["MyGem"] -> [#<Decode::Language::Ruby::Module:...>]
+  MyGem
+["MyGem", "User"] -> [#<Decode::Language::Ruby::Class:...>]
+    MyGem::User
+["MyGem", "User", "initialize"] -> [#<Decode::Language::Ruby::Method:...>]
+      MyGem::User#initialize
+```
+
+### Extract Documentation
+
+```bash
+# Extract all documentation from your codebase
+bake decode:index:documentation lib
+```
+
+This outputs formatted documentation for all documented definitions:
+
+~~~markdown
+## `MyGem::User#initialize`
+
+Initialize a new user with the given email address.
+
+## `MyGem::User#authenticate`
+
+Authenticate the user with a password.
+Returns true if authentication is successful.
+~~~
+
+## Achieving 100% Coverage
+
+### Document all public APIs
+
+```ruby
+# A user account with authentication and email.
+class User
+	# @attribute [String] The user's email address.
+	attr_reader :email
+	
+	# Initialize a new user.
+	# @parameter email [String] The user's email address.
+	def initialize(email)
+		# Store the email address:
+		@email = email
+	end
+end
+```
+
+### Use @namespace for organizational modules
+
+The best place to add these by default is `version.rb`.
+
+```ruby
+# @namespace
+module MyGem
+	VERSION = "0.1.0"
+end
+```
+
+### Document edge cases
+
+```ruby
+# @private
+def internal_helper
+	# Add the fields:
+	return foo + bar
+end
+```
+
+### Common Coverage Issues
+
+#### Missing namespace documentation
+
+```ruby
+# This module has no documentation and will show as missing coverage:
+module MyGem
+end
+
+# Solution: Add @namespace pragma:
+# @namespace
+module MyGem
+	# Provides core functionality.
+end
+```
+
+#### Undocumented methods
+
+Problem: Methods without any comments will show as missing coverage:
+```ruby
+def process_data
+	# Implementation here
+end
+```
+
+Solution: Add description and pragmas:
+```ruby
+# Process the input data and return results.
+# @parameter data [Hash] Input data to process.
+# @returns [Array] Processed results.
+def process_data(data)
+	# Process the input:
+	results = data.map{|item| transform(item)}
+	
+	# Return processed results:
+	results
+end
+```
+
+#### Missing attr documentation
+
+Problem: Attributes without documentation will show as missing coverage:
+```ruby
+attr_reader :name
+```
+
+Solution: Document with @attribute pragma:
+```ruby
+# @attribute [String] The user's full name.
+attr_reader :name
+```
+
+## Integrating into CI/CD
+
+### GitHub Actions Example
+
+```yaml
+name: Documentation Coverage
+
+on: [push, pull_request]
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+      - name: Check documentation coverage
+        run: bake decode:index:coverage lib
+```
+
+### Rake Task Integration
+
+Add to your `Rakefile`:
+
+```ruby
+require "decode"
+
+desc "Check documentation coverage"
+task :doc_coverage do
+	system("bake decode:index:coverage lib") || exit(1)
+end
+
+task default: [:test, :doc_coverage]
+```