decode 0.25.0 → 0.26.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01244e4f44a9916295cace389ef8ad2116277a1e5831f500d1e13d953290386a
-  data.tar.gz: e3a85a7b3c2c4d98aa8acc50026a2b515bc33db95fff2ec82c117cda0c1ded52
+  metadata.gz: 453b1f28ebb358dd7f37f17d12e6e48616895970d0a9a9225ddb8d3384f2fc90
+  data.tar.gz: 3720af135885d5d002f91a3bc758a3f04e58c1d7022fc4d90b008754568b66d2
 SHA512:
-  metadata.gz: 974b45b31551d81b281fe5a483a93e0b3ed07a3b6508dbd30df014b45cc2b47a51a34ae6f20454bd973ec7fe5c23393a7176c20028e6dba9a1402fb987c79eb2
-  data.tar.gz: 5028c457dc3c24d79996170725604fddffc127f96a96f8fdf5c3c4188162097538cb103be51808d125e3ed3edec786104874123197bd6e37bd8e463fcf7319b5
+  metadata.gz: cf74b8ffc88195be9440a81aeceb0da5b2b77ff9c2e45df2961f683b27ed15f1d5ccab54d161f05931d2c9c5fdd5641b50b6122757b91d55d3a5668c8dcbde1a
+  data.tar.gz: 417e14f2501bdb368a25f5872915d4d3de47cd57f39164977c4a42b372ab41f4a9d4d435644972297f076c84cc3d475f732a4d90677ba0bb7b01e897586ca9b1

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
+# Represents 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
+# Represents a user management system.
+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]
+```

data/context/getting-started.md

@@ -1,242 +1,54 @@
-# Getting Started with Decode
+# Getting Started
 
-The Decode gem provides programmatic access to Ruby code structure and metadata. It can parse Ruby files and extract definitions, comments, and documentation pragmas, enabling code analysis, documentation generation, and other programmatic manipulations of Ruby codebases.
+This guide explains how to use `decode` for source code analysis.
 
 ## Installation
 
-Add to your Gemfile:
+Add the gem to your project:
 
-```ruby
-gem 'decode'
-```
+~~~ bash
+$ bundle add decode
+~~~
 
-Or install directly:
+## Indexing
 
-```bash
-bundle add decode
-```
+`decode` turns your source code into a kind of database with rich access to definitions, segments and associated comments. Use {ruby Decode::Index} to build an index of your project by loading in source files:
 
-## Basic Usage
+~~~ ruby
+require 'decode/index'
 
-### Analyzing a Ruby File
-
-```ruby
-require 'decode'
-
-# Create a source object:
-source = Decode::Source.new('lib/my_class.rb', Decode::Language::Ruby.new)
-
-# Extract definitions (classes, methods, etc.):
-definitions = source.definitions.to_a
-
-definitions.each do |definition|
-  puts "#{definition.name}: #{definition.short_form}"
-end
-```
+index = Decode::Index.new
 
-### Extracting Documentation
+# Load all Ruby files into the index:
+index.update(Dir['**/*.rb'])
+~~~
 
-```ruby
-# Get segments (blocks of comments + code):
-segments = source.segments.to_a
+Once you've done this, you can print out all the definitions from your project:
 
-segments.each do |segment|
-  puts "Comments: #{segment.comments.join(' ')}"
-  puts "Code: #{segment.code}"
+~~~ ruby
+index.definitions.each do |name, symbol|
+	puts symbol.long_form
 end
-```
-
-### Checking Documentation Coverage
+~~~
 
-```ruby
-# Check which definitions have documentation:
-definitions.each do |definition|
-  status = definition.comments.any? ? 'documented' : 'missing docs'
-  puts "#{definition.name}: #{status}"
-end
-```
-
-## Working with Documentation Pragmas
-
-The Decode gem understands structured documentation pragmas:
-
-```ruby
-# This will be parsed and structured:
-source_code = <<~RUBY
-  # Represents a user in the system.
-  class User
-    # @attribute [String] The user's email address.
-    attr_reader :email
-    
-    # Initialize a new user.
-    # @parameter email [String] The user's email address.
-    # @parameter options [Hash] Additional options.
-    # @option :active [bool] Whether the account is active.
-    # @raises [ArgumentError] If email is invalid.
-    def initialize(email, options = {})
-      # Validate the email format:
-      raise ArgumentError, "Invalid email" if email.empty?
-      
-      # Set instance variables:
-      @email = email
-      @active = options.fetch(:active, true)
-    end
-  end
-RUBY
-
-# Parse and analyze:
-result = Decode::Language::Ruby.new.parser.parse_source(source_code)
-definitions = Decode::Language::Ruby.new.parser.definitions_for(source_code).to_a
-
-definitions.each do |definition|
-  puts "#{definition.name}: #{definition.comments.join(' ')}"
-end
-```
-
-## Common Use Cases
-
-### 1. Code Analysis and Metrics
-
-```ruby
-# Analyze a codebase and return metrics.
-# @parameter file_path [String] Path to the Ruby file to analyze.
-def analyze_codebase(file_path)
-  source = Decode::Source.new(file_path, Decode::Language::Ruby.new)
-  definitions = source.definitions.to_a
-  
-  # Count different definition types:
-  classes = definitions.count { |d| d.is_a?(Decode::Language::Ruby::Class) }
-  methods = definitions.count { |d| d.is_a?(Decode::Language::Ruby::Method) }
-  modules = definitions.count { |d| d.is_a?(Decode::Language::Ruby::Module) }
-  
-  puts "Classes: #{classes}, Methods: #{methods}, Modules: #{modules}"
-end
-```
-
-### 2. Documentation Coverage Reports
-
-```ruby
-# Calculate documentation coverage for a file.
-# @parameter file_path [String] Path to the Ruby file to analyze.
-def documentation_coverage(file_path)
-  source = Decode::Source.new(file_path, Decode::Language::Ruby.new)
-  definitions = source.definitions.to_a
-  
-  # Calculate coverage statistics:
-  total = definitions.count
-  documented = definitions.count { |d| d.comments.any? }
-  
-  puts "Coverage: #{documented}/#{total} (#{(documented.to_f / total * 100).round(1)}%)"
-end
-```
-
-### 3. Extracting API Information
-
-```ruby
-# Extract API information from a Ruby file.
-# @parameter file_path [String] Path to the Ruby file to analyze.
-def extract_api_info(file_path)
-  source = Decode::Source.new(file_path, Decode::Language::Ruby.new)
-  definitions = source.definitions.to_a
-  
-  # Get public methods only:
-  public_methods = definitions.select do |definition|
-    definition.is_a?(Decode::Language::Ruby::Method) && 
-    definition.visibility == :public
-  end
-  
-  public_methods.each do |method|
-    puts "#{method.long_form}"
-    puts "  Comments: #{method.comments.join(' ')}" if method.comments.any?
-  end
-end
-```
-
-### 4. Code Structure Analysis
-
-```ruby
-# Analyze the structure of Ruby files in a directory.
-# @parameter directory [String] Path to the directory to analyze.
-def analyze_structure(directory)
-  Dir.glob("#{directory}/**/*.rb").each do |file|
-    source = Decode::Source.new(file, Decode::Language::Ruby.new)
-    definitions = source.definitions.to_a
-    
-    # Find nested classes and modules:
-    nested = definitions.select { |d| d.parent }
-    
-    if nested.any?
-      puts "#{file}:"
-      nested.each do |definition|
-        puts "  #{definition.qualified_name}"
-      end
-    end
-  end
-end
-```
-
-### 5. Finding Undocumented Code
-
-```ruby
-# Find undocumented code in a directory.
-# @parameter directory [String] Path to the directory to analyze.
-def find_undocumented(directory)
-  Dir.glob("#{directory}/**/*.rb").each do |file|
-    source = Decode::Source.new(file, Decode::Language::Ruby.new)
-    definitions = source.definitions.to_a
-    
-    # Filter for undocumented public definitions:
-    undocumented = definitions.select { |d| d.comments.empty? && d.visibility == :public }
-    
-    if undocumented.any?
-      puts "#{file}:"
-      undocumented.each do |definition|
-        puts "  - #{definition.short_form}"
-      end
-    end
-  end
-end
-```
-
-## Advanced Features
-
-### Using the Index
-
-```ruby
-# Create an index for multiple files:
-index = Decode::Index.new
-index.update(Dir.glob("lib/**/*.rb"))
-
-# Search through the index:
-index.trie.traverse do |path, node, descend|
-  if node.values
-    node.values.each do |definition|
-      puts "#{path.join('::')} - #{definition.short_form}"
-    end
-  end
-  descend.call
-end
-```
+## References
 
-### Custom Language Support
+References are strings which can be resolved into definitions. The index allows you to efficiently resolve references.
 
-```ruby
-# The decode gem is extensible:
-language = Decode::Language::Generic.new("custom")
-# You can implement your own parser for other languages:
-```
+~~~ ruby
+# Lookup a specific symbol:
+reference = index.languages.parse_reference("ruby Decode::Index#lookup")
+definition = index.lookup(reference).first
+puts definition.long_form
+~~~
 
-## Tips for Effective Usage
+## Documentation
 
-1. **Use structured pragmas** - They help tools understand your code better.
-2. **Leverage programmatic access** - Build tools that analyze and manipulate code.
-3. **Use @namespace** - For organizational modules to achieve complete coverage.
-4. **Analyze code patterns** - Use decode to understand codebase structure.
-5. **Build automation** - Use decode in CI/CD pipelines for code quality checks.
+The {ruby Decode::Documentation} provides rich access to the comments that preceed a definition. This includes metadata including `@parameter`, `@returns` and other tags.
 
-## Next Steps
+~~~ ruby
+lines = definition.documentation.text
+puts lines
+~~~
 
-- See [Ruby Documentation](ruby-documentation.md) for complete pragma reference.
-- Check out [Documentation Coverage](coverage.md) for coverage monitoring.
-- Use decode to build code analysis tools for your projects.
-- Integrate decode into your development workflow and CI/CD pipelines.
+See {ruby Decode::Comment::Node#traverse} for more details about how to consume this data.

data/context/index.yaml

@@ -0,0 +1,22 @@
+# Automatically generated context index for Utopia::Project guides.
+# Do not edit then files in this directory directly, instead edit the guides and then run `bake utopia:project:agent:context:update`.
+---
+description: Code analysis for documentation generation.
+metadata:
+  documentation_uri: https://socketry.github.io/decode/
+  funding_uri: https://github.com/sponsors/socketry/
+  source_code_uri: https://github.com/socketry/decode.git
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: This guide explains how to use `decode` for source code analysis.
+- path: documentation-coverage.md
+  title: Documentation Coverage
+  description: This guide explains how to test and monitor documentation coverage
+    in your Ruby projects using the Decode gem's built-in bake tasks.
+- path: ruby-documentation.md
+  title: Ruby Documentation
+  description: This guide covers documentation practices and pragmas supported by
+    the Decode gem for documenting Ruby code. These pragmas provide structured documentation
+    that can be parsed and used to generate API documentation and achieve complete
+    documentation coverage.

data/context/ruby-documentation.md

@@ -8,27 +8,27 @@ 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.
-- **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.
+- 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.
+- 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.
 
 #### Inline Code Comments
 
-- **Explanatory comments**: Comments within methods that explain specific lines or sections of code should end with a colon `:` to distinguish them from definition documentation.
-- **Purpose**: These comments explain the reasoning behind specific implementation details.
+- Explanatory comments: Comments within methods that explain specific lines or sections of code should end with a colon `:` to distinguish them from definition documentation.
+- Purpose: These comments explain the reasoning behind specific implementation details.
 
 #### Links and Code Formatting
 
-- **Curly braces `{}`**: Use curly braces to create links to other methods, classes, or modules. The Decode gem uses `@index.lookup(text)` to resolve these references.
-	- **Absolute references**: `{Decode::Index#lookup}` - Links to a specific method in a specific class
-	- **Relative references**: `{lookup}` - Links to a method in the current scope or class
-	- **Class references**: `{User}` - Links to a class or module
-- **Backticks**: Use backticks for code formatting of symbols, values, method names, and technical terms that should appear in monospace font.
-	- **Symbols**: `:admin`, `:user`, `:guest`
-	- **Values**: `true`, `false`, `nil`
-	- **Technical terms**: `attr_*`, `catch`/`throw`
-	- **Code expressions**: `**options`
+- Curly braces `{}`: Use curly braces to create links to other methods, classes, or modules. The Decode gem uses `@index.lookup(text)` to resolve these references.
+  - Absolute references: `{Decode::Index#lookup}` - Links to a specific method in a specific class
+  - Relative references: `{lookup}` - Links to a method in the current scope or class
+  - Class references: `{User}` - Links to a class or module
+- Backticks: Use backticks for code formatting of symbols, values, method names, and technical terms that should appear in monospace font.
+  - Symbols: `:admin`, `:user`, `:guest`
+  - Values: `true`, `false`, `nil`
+  - Technical terms: `attr_*`, `catch`/`throw`
+  - Code expressions: `**options`
 
 #### Examples
 
@@ -98,14 +98,14 @@ end
 
 ### Best Practices
 
-1. **Be Consistent**: Use the same format for similar types of documentation.
-2. **Include Types**: Always specify types for parameters, returns, and attributes.
-3. **Be Descriptive**: Provide clear, actionable descriptions.
-4. **Document Exceptions**: Always document what exceptions might be raised.
-5. **Use Examples**: Include usage examples when the behavior isn't obvious.
-6. **Keep Updated**: Update documentation when you change the code.
-7. **Use @namespace wisely**: Apply to organizational modules to achieve 100% coverage.
-8. **Avoid redundancy**: For simple attributes and methods, attach descriptions directly to pragmas rather than repeating obvious information.
+1. Be Consistent: Use the same format for similar types of documentation.
+2. Include Types: Always specify types for parameters, returns, and attributes.
+3. Be Descriptive: Provide clear, actionable descriptions.
+4. Document Exceptions: Always document what exceptions might be raised.
+5. Use Examples: Include usage examples when the behavior isn't obvious.
+6. Keep Updated: Update documentation when you change the code.
+7. Use @namespace wisely: Apply to organizational modules to achieve 100% coverage.
+8. Avoid redundancy: For simple attributes and methods, attach descriptions directly to pragmas rather than repeating obvious information.
 
 #### Simple Attributes and Methods
 
@@ -247,14 +247,14 @@ Documents block parameters and behavior.
 
 ```ruby
 # @yields {|item| ...} Each item in the collection.
-#   @parameter item [Object] The current item being processed.
+# 	@parameter item [Object] The current item being processed.
 def each_item(&block)
 	items.each(&block)
 end
 
 # @yields {|user, index| ...} User and their index.
-#   @parameter user [User] The current user.
-#   @parameter index [Integer] The user's position in the list.
+# 	@parameter user [User] The current user.
+# 	@parameter index [Integer] The user's position in the list.
 def each_user_with_index(&block)
 	users.each_with_index(&block)
 end
@@ -308,6 +308,39 @@ def fetch_data
 end
 ```
 
+### Example Code
+
+#### `@example Title?`
+
+Includes an example usage snippet for a method or definition. The `@example` directive can have an optional title on the same line, followed by one or more indented lines of code:
+
+```ruby
+# @example Create a new thing
+# 	thing = Thing.new
+# 	thing.process
+def process
+	# ...
+end
+```
+
+Behaviour:
+
+- The optional title is captured verbatim (e.g., `"Create a new thing"`).
+- Indented lines following the directive are captured as the example code.
+- When parsed, examples are available as `Decode::Comment::Example` nodes with:
+	- `title` – `String?`, the optional example title.
+	- `text` – `Array(String)?`, the raw code lines (including leading indentation).
+	- `code` – `String?`, the code as a single string with leading indentation removed (convenience).
+
+Multiple `@example` pragmas can be used on the same definition to show different scenarios.
+
+```ruby
+definition.documentation.filter(Decode::Comment::Example) do |example|
+	puts "Title: #{example.title.inspect}"
+	puts example.code # => joined string with indentation removed
+end
+```
+
 ### Namespace Documentation
 
 #### `@namespace`

data/lib/decode/comment/constant.rb

@@ -44,4 +44,4 @@ module Decode
 			attr :type
 		end
 	end
-end 
+end