decode 0.22.0 → 0.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dd0b7516d4dffc4eeb854093c5fe7b05776dcee117eeeecafe86c5b1c8309b3c
-  data.tar.gz: 92080e0cfe0e151f1cd5093414b4cd9deef5bcc30aa50e0abd4bc49d1e0fd2b5
+  metadata.gz: ddd2b15f3019877bc34174d6d75e65d435431d6b4642fe6806c01cb44a154d20
+  data.tar.gz: 99d6be44ed79584ba17a8ed8479c976890aac2a621d4be6ac0f0ab3edef86c9f
 SHA512:
-  metadata.gz: b88d0a989f34575cbd8a2aa141769e2f5426c4f6b6639925458bd18fac6f873c525c3391bb17a78feb72daf3570a85899a1160f832ff1a60f1604ef08523938b
-  data.tar.gz: 415dc8eb4f66d3832f7790522b605a7ef32eae6528b1da7c91f6e54770f01f39397d87196b3c3770b27eb3634883bd148f5bd4165c9fe55e3494c7ae4b727a8d
+  metadata.gz: 6015f4796c39f6c187fdf42fc872da64d85f4472ed1a641c74255a6a39c5cf411b30e31d55eabb8211c09d0d04030eabc23e1cd850d6ecdb92c50e9c72e25388
+  data.tar.gz: 32bb1229c0b4dca21f0334b13c2742dc3b5963f8252da77377b2687322ee94c60b8a2b313df410e113f1865bd48b65be05b3756f968de77de27d238d54001f27

data/bake/decode/index.rb

@@ -6,8 +6,8 @@
 def initialize(...)
 	super
 	
-	require 'decode/index'
-	require 'set'
+	require "decode/index"
+	require "set"
 end
 
 # Process the given source root and report on comment coverage.
@@ -19,7 +19,7 @@ def coverage(root)
 	index.update(paths)
 	
 	documented = Set.new
-	missing = Set.new
+	missing = {}
 	
 	index.trie.traverse do |path, node, descend|
 		public_definition = node.values.nil?
@@ -28,10 +28,10 @@ def coverage(root)
 			if definition.public?
 				level = path.size
 				
-				if definition.comments.nil?
-					missing << definition.qualified_name
-				else
+				if definition.documented?
 					documented << definition.qualified_name
+				else
+					missing[definition.qualified_name] ||= definition
 				end
 				
 				public_definition = true
@@ -45,7 +45,9 @@ def coverage(root)
 	end
 	
 	# Since there can be multiple definitions for a given symbol, we can ignore any missing definitions that have been documented elsewhere:
-	missing = missing - documented
+	documented.each do |qualified_name|
+		missing.delete(qualified_name)
+	end
 	
 	documented_count = documented.size
 	public_count = documented_count + missing.size
@@ -53,8 +55,13 @@ def coverage(root)
 	
 	if documented_count < public_count
 		$stderr.puts nil, "Missing documentation for:"
-		missing.each do |name|
-			$stderr.puts "- #{name}"
+		missing.each do |qualified_name, definition|
+			location = definition.location
+			if location
+				$stderr.puts "- #{qualified_name} (#{location.path}:#{location.line})"
+			else
+				$stderr.puts "- #{qualified_name}"
+			end
 		end
 		
 		raise RuntimeError, "Insufficient documentation!"

data/context/coverage.md

@@ -0,0 +1,325 @@
+# 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
+```
+
+### Understanding Coverage Output
+
+When you run the coverage command, you'll see output like:
+
+```
+15 definitions have documentation, out of 20 public definitions.
+
+Missing documentation for:
+- MyGem::SomeClass#method_name
+- MyGem::AnotherClass
+- MyGem::Utility.helper_method
+```
+
+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`).
+- 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 [Boolean] 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
+
+### Strategy for Complete Coverage
+
+1. **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
+   ```
+
+2. **Use @namespace for organizational modules**
+   ```ruby
+   # @namespace
+   module MyGem
+     # Contains the main functionality.
+   end
+   ```
+
+3. **Document edge cases**
+   ```ruby
+   # @private
+   def internal_helper
+     # Internal implementation details.
+   end
+   ```
+
+### Common Coverage Issues
+
+**Issue: 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
+```
+
+**Issue: 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
+```
+
+**Issue: 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]
+```
+
+## Monitoring Coverage Over Time
+
+### Generate Coverage Reports
+
+```ruby
+# Generate a coverage percentage for the specified directory.
+# @parameter root [String] The root directory to analyze.
+# @returns [Float] The coverage percentage.
+def coverage_percentage(root)
+  index = Decode::Index.new
+  index.update(Dir.glob(File.join(root, "**/*.rb")))
+  
+  documented = 0
+  total = 0
+  
+  index.trie.traverse do |path, node, descend|
+    node.values&.each do |definition|
+      if definition.public?
+        total += 1
+        documented += 1 if definition.comments&.any?
+      end
+    end
+    descend.call if node.values.nil?
+  end
+  
+  (documented.to_f / total * 100).round(2)
+end
+
+puts "Coverage: #{coverage_percentage('lib')}%"
+```
+
+### Exclude Patterns
+
+If you need to exclude certain files from coverage:
+
+```ruby
+# Custom coverage script with exclusions.
+paths = Dir.glob("lib/**/*.rb").reject do |path|
+  # Exclude vendor files and test files:
+  path.include?('vendor/') || path.end_with?('_test.rb')
+end
+
+index = Decode::Index.new
+index.update(paths)
+# ... continue with coverage analysis
+```
+
+## Best Practices
+
+1. **Run coverage checks regularly** - Include in your CI pipeline
+2. **Set coverage targets** - Aim for 100% coverage of public APIs
+3. **Document incrementally** - Add documentation as you write code
+4. **Use meaningful descriptions** - Don't just add empty comments
+5. **Leverage @namespace** - For modules that only serve as containers
+6. **Review coverage reports** - Use the missing documentation list to prioritize
+
+## Troubleshooting
+
+### Common Error Messages
+
+**"Insufficient documentation!"**
+- Some public definitions are missing documentation
+- Check the list of missing items and add appropriate comments
+
+**No output from coverage command**
+- Verify the path exists: `bake decode:index:coverage lib`
+- Check that Ruby files exist in the specified directory
+
+**Coverage shows 0/0 definitions**
+- The directory might not contain any Ruby files
+- Try a different path or check your file extensions
+
+### Debug Coverage Issues
+
+```bash
+# First, see what symbols are being detected
+bake decode:index:symbols lib
+
+# Then check what documentation exists
+bake decode:index:documentation lib
+
+# Finally, run coverage to see what's missing
+bake decode:index:coverage lib
+```
+
+This workflow helps you understand what the tool is detecting and why certain items might be missing documentation.

data/context/getting-started.md

@@ -0,0 +1,242 @@
+# Getting Started with Decode
+
+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.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'decode'
+```
+
+Or install directly:
+
+```bash
+bundle add decode
+```
+
+## Basic Usage
+
+### 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
+```
+
+### Extracting Documentation
+
+```ruby
+# Get segments (blocks of comments + code):
+segments = source.segments.to_a
+
+segments.each do |segment|
+  puts "Comments: #{segment.comments.join(' ')}"
+  puts "Code: #{segment.code}"
+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 [Boolean] 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
+```
+
+### Custom Language Support
+
+```ruby
+# The decode gem is extensible:
+language = Decode::Language::Generic.new("custom")
+# You can implement your own parser for other languages:
+```
+
+## Tips for Effective Usage
+
+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.
+
+## Next Steps
+
+- 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.