tryouts 3.5.0 → 3.5.2

data/lib/tryouts/parsers/CLAUDE.md

@@ -0,0 +1,178 @@
+In Ruby 3.4+, `case/when` and `case/in` represent fundamentally different approaches to conditional logic:
+
+## `case/when` - Traditional Equality Matching
+
+Uses the `===` operator for comparison. Simple and straightforward:
+
+```ruby
+def classify_response(status)
+  case status
+  when 200..299
+    "success"
+  when 400..499
+    "client_error"
+  when 500..599
+    "server_error"
+  when String
+    "string_status"
+  else
+    "unknown"
+  end
+end
+```
+
+## `case/in` - Pattern Matching with Destructuring
+
+Matches structure and binds variables. Much more powerful:
+
+```ruby
+def process_api_response(response)
+  case response
+  in { status: 200, data: { user: { name: String => name, age: Integer => age } } }
+    "User #{name} is #{age} years old"
+
+  in { status: 200, data: Array => items } if items.length > 10
+    "Got #{items.length} items"
+
+  in { status: 400..499, error: { message: msg } }
+    "Client error: #{msg}"
+
+  in { status: 500.. }
+    "Server error occurred"
+
+  in nil | {}
+    "Empty response"
+  else
+    "Unexpected response format"
+  end
+end
+```
+
+## Key Differences
+
+### 1. **Variable Binding**
+
+```ruby
+# case/when - no binding
+case user
+when Hash
+  puts user[:name]  # Must access manually
+end
+
+# case/in - automatic binding
+case user
+in { name: String => username, age: }  # 'age' variable created automatically
+  puts username  # Bound variable available
+end
+```
+
+### 2. **Structural Matching**
+
+```ruby
+# case/when - only surface comparison
+case data
+when Array
+  # Know it's an array, but not its contents
+end
+
+# case/in - deep structure matching
+case data
+in [first, *middle, last] if middle.length > 2
+  # Automatically destructured with guard condition
+end
+```
+
+### 3. **Guard Conditions**
+
+```ruby
+# case/when - separate if needed
+case number
+when Integer
+  if number > 100
+    "big integer"
+  else
+    "small integer"
+  end
+end
+
+# case/in - integrated guards
+case number
+in Integer => n if n > 100
+  "big integer"
+in Integer
+  "small integer"
+end
+```
+
+## Practical Example for Tryouts
+
+For parsing tryout lines, here's the difference:
+
+### Traditional `case/when`
+```ruby
+def parse_line(line)
+  case line
+  when /^##\s*(.+)/
+    [:description, $1.strip]
+  when /^#=>\s*(.+)/
+    [:expectation, $1.strip]
+  when /^#=\?>\s*(.+)/
+    [:debug_info, $1.strip]
+  else
+    [:code, line]
+  end
+end
+```
+
+### Pattern Matching `case/in`
+```ruby
+def parse_line(line)
+  case line
+  in /^##\s*(.+)/ => description
+    [:description, description.strip]
+  in /^#=>\s*(.+)/ => expectation
+    [:expectation, expectation.strip]
+  in /^#=\?>\s*(.+)/ => debug_expr
+    [:debug_info, debug_expr.strip]
+  in /^\s*$/
+    [:blank]
+  else
+    [:code, line]
+  end
+end
+```
+
+## When to Use Which
+
+### Use `case/when` for:
+- Simple value comparisons
+- Class/type checking
+- Range matching
+- Traditional switch-like logic
+
+### Use `case/in` for:
+- Complex data structure matching
+- When you need variable binding
+- Guard conditions
+- Destructuring arrays/hashes
+- Multiple conditions per branch
+
+## Ruby 3.4+ Enhancements
+
+Ruby 3.4 added several pattern matching improvements:
+
+```ruby
+# Variable binding in array patterns
+case data
+in [String => first, *String => middle, String => last]
+  # All string array with bound variables
+end
+
+# Hash patterns with rest
+case config
+in { required: true, **rest } if rest.keys.all? { |k| k.is_a?(Symbol) }
+  # Required config with symbol keys only
+end
+```
+
+For the Tryouts modernization, `case/in` provides cleaner syntax for parsing complex comment patterns while binding the captured content directly to variables, eliminating the need for global match variables like `$1`.

data/lib/tryouts/parsers/base_parser.rb

@@ -6,11 +6,89 @@ require_relative 'shared_methods'
 require_relative '../parser_warning'
 
 class Tryouts
-  # Fixed PrismParser with pattern matching for robust token filtering
   module Parsers
+    # Base class for all tryout parsers providing common functionality
+    #
+    # BaseParser establishes the foundation for parsing tryout files by handling
+    # file loading, Prism integration, and providing shared parsing infrastructure.
+    # All concrete parser implementations (EnhancedParser, LegacyParser) inherit
+    # from this class.
+    #
+    # @abstract Subclass and implement {#parse} to create a concrete parser
+    # @example Implementing a custom parser
+    #   class MyCustomParser < Tryouts::Parsers::BaseParser
+    #     def parse
+    #       # Your parsing logic here
+    #       # Must return a Tryouts::Testrun object
+    #     end
+    #
+    #     private
+    #
+    #     def parser_type
+    #       :custom
+    #     end
+    #   end
+    #
+    # @!attribute [r] source_path
+    #   @return [String] Path to the source file being parsed
+    # @!attribute [r] source
+    #   @return [String] Raw source code content
+    # @!attribute [r] lines
+    #   @return [Array<String>] Source lines with line endings removed
+    # @!attribute [r] prism_result
+    #   @return [Prism::ParseResult] Result of parsing source with Prism
+    # @!attribute [r] parsed_at
+    #   @return [Time] Timestamp when parsing was initiated
+    # @!attribute [r] options
+    #   @return [Hash] Parser configuration options
+    # @!attribute [r] warnings
+    #   @return [Array<Tryouts::ParserWarning>] Collection of parsing warnings
+    #
+    # ## Shared Functionality
+    #
+    # ### 1. File and Source Management
+    # - Automatic file reading and line splitting
+    # - UTF-8 encoding handling
+    # - Path normalization and validation
+    #
+    # ### 2. Prism Integration
+    # - Automatic Prism parsing of source code
+    # - Syntax error detection and handling
+    # - AST access for advanced parsing needs
+    #
+    # ### 3. Warning System
+    # - Centralized warning collection and management
+    # - Type-safe warning objects with context
+    # - Integration with output formatters
+    #
+    # ### 4. Shared Methods
+    # - Token grouping and classification logic
+    # - Test case boundary detection
+    # - Common utility methods for all parsers
+    #
+    # ## Parser Requirements
+    #
+    # Concrete parser implementations must:
+    # 1. Implement the abstract `parse` method
+    # 2. Return a `Tryouts::Testrun` object
+    # 3. Handle syntax errors appropriately
+    # 4. Provide a unique `parser_type` identifier
+    #
+    # @see EnhancedParser For Prism-based comment extraction
+    # @see LegacyParser For line-by-line parsing approach
+    # @see SharedMethods For common parsing utilities
+    # @since 3.0.0
     class BaseParser
       include Tryouts::Parsers::SharedMethods
 
+      # Initialize a new parser instance
+      #
+      # @param source_path [String] Absolute path to the tryout source file
+      # @param options [Hash] Configuration options for parsing behavior
+      # @option options [Boolean] :strict Enable strict mode validation
+      # @option options [Boolean] :warnings Enable warning collection (default: true)
+      # @raise [Errno::ENOENT] If source file doesn't exist
+      # @raise [Errno::EACCES] If source file isn't readable
       def initialize(source_path, options = {})
         @source_path  = source_path
         @source       = File.read(source_path)
@@ -21,6 +99,28 @@ class Tryouts
         @warnings     = []
       end
 
+      # Parse the source file into structured test data
+      #
+      # @abstract Subclasses must implement this method
+      # @return [Tryouts::Testrun] Parsed test structure with setup, tests, teardown, and warnings
+      # @raise [NotImplementedError] If called directly on BaseParser
+      def parse
+        raise NotImplementedError, "Subclasses must implement #parse"
+      end
+
+      protected
+
+      # Get the parser type identifier
+      #
+      # @abstract Subclasses should override to provide unique identifier
+      # @return [Symbol] Parser type identifier
+      def parser_type
+        :base
+      end
+
+      # Access to instance variables for subclasses
+      attr_reader :source_path, :source, :lines, :prism_result, :parsed_at, :options
+
     end
   end
 end

data/lib/tryouts/parsers/enhanced_parser.rb

@@ -1,16 +1,74 @@
 # lib/tryouts/parsers/enhanced_parser.rb
 
-# Enhanced parser using Prism's inhouse comment extraction capabilities
-# Drop-in replacement for PrismParser that eliminates HEREDOC parsing issues
-
 require_relative '../test_case'
 require_relative 'base_parser'
 
 class Tryouts
-  # Enhanced parser that replaces manual line-by-line parsing with inhouse Prism APIs
-  # while maintaining full compatibility with the original parser's logic structure
+  # Enhanced parser using Prism's native comment extraction for robust parsing
+  #
+  # The EnhancedParser is the default parser that provides syntax-aware comment
+  # extraction by leveraging Ruby's official Prism parser. This approach eliminates
+  # common parsing issues found in regex-based parsers, particularly with complex
+  # Ruby syntax.
+  #
+  # @example Basic usage
+  #   parser = Tryouts::EnhancedParser.new(source_code, file_path)
+  #   testrun = parser.parse
+  #   puts testrun.test_cases.length
+  #
+  # @example Problematic code that EnhancedParser handles correctly
+  #   source = <<~RUBY
+  #     ## Test HEREDOC handling
+  #     sql = <<~SQL
+  #       SELECT * FROM users
+  #       -- This is NOT a tryout comment
+  #       #=> This is NOT a tryout expectation
+  #     SQL
+  #     puts sql.length
+  #     #=> Integer  # This IS a real expectation
+  #   RUBY
+  #
+  # @!attribute [r] parser_type
+  #   @return [Symbol] Returns :enhanced to identify parser type
+  #
+  # ## Key Benefits over LegacyParser
+  #
+  # ### 1. HEREDOC Safety
+  # - Uses Prism's `parse_comments()` to extract only actual Ruby comments
+  # - Automatically excludes content inside string literals, HEREDOCs, and interpolation
+  # - Prevents false positive expectation detection
+  #
+  # ### 2. Inline Comment Handling
+  # - Correctly handles lines with both code and comments
+  # - Supports multiple comments per line with proper positioning
+  # - Emits separate tokens for code and comment content
+  #
+  # ### 3. Syntax Awareness
+  # - Leverages Ruby's official parser for accurate code understanding
+  # - Handles complex Ruby syntax edge cases reliably
+  # - More robust than regex-based parsing approaches
+  #
+  # ### 4. Performance
+  # - Uses optimized C-based Prism parsing for comment extraction
+  # - Efficient handling of large files with complex syntax
+  #
+  # ## Pattern Matching
+  # Uses Ruby 3.4+ pattern matching (`case/in`) for token classification,
+  # providing clean, modern syntax for expectation type detection.
+  #
+  # @see LegacyParser For simpler regex-based parsing (legacy compatibility)
+  # @see BaseParser For shared parsing functionality
+  # @since 3.2.0
   class EnhancedParser < Tryouts::Parsers::BaseParser
 
+    # Parse source code into a Testrun using Prism-based comment extraction
+    #
+    # This method provides the main parsing logic that converts raw Ruby source
+    # code containing tryout syntax into structured test cases. Uses Prism's
+    # native comment extraction to avoid HEREDOC parsing issues.
+    #
+    # @return [Tryouts::Testrun] Structured test data with setup, test cases, teardown, and warnings
+    # @raise [Tryouts::TryoutSyntaxError] If source contains syntax errors or strict mode violations
     def parse
       return handle_syntax_errors if @prism_result.failure?
 
@@ -25,7 +83,20 @@ class Tryouts
 
     private
 
-    # Inhouse comment extraction - replaces the manual regex parsing
+    # Extract and tokenize comments using Prism's native comment extraction
+    #
+    # This method replaces manual line-by-line regex parsing with Prism's
+    # built-in comment extraction capabilities. The key benefit is that
+    # `Prism.parse_comments()` only returns actual Ruby comments, automatically
+    # excluding content inside string literals, HEREDOCs, and interpolations.
+    #
+    # @return [Array<Hash>] Array of token hashes with keys :type, :content, :line, etc.
+    # @example Token structure
+    #   [
+    #     { type: :description, content: "Test case description", line: 5 },
+    #     { type: :code, content: "result = calculate(x)", line: 6 },
+    #     { type: :expectation, content: "42", line: 7, ast: <Prism::Node> }
+    #   ]
     def tokenize_content_with_inhouse_extraction
       tokens = []
 
@@ -47,8 +118,8 @@ class Tryouts
                 tokens << { type: :code, content: line, line: index, ast: parse_ruby_line(line) }
                 emitted_code = true
               end
-              # Inline comment may carry expectations; classify it too
-              tokens << classify_comment_inhousely(comment_content, line_number)
+              # Inline comment (after code) - treat as regular comment, not expectation
+              tokens << { type: :comment, content: comment_content.sub(/^#\s*/, ''), line: line_number - 1 }
             else
               tokens << classify_comment_inhousely(comment_content, line_number)
             end
@@ -69,44 +140,125 @@ class Tryouts
       tokens
     end
 
-    # Inhouse comment classification - replaces complex regex patterns
+    # Classify comment content into specific token types using pattern matching
+    #
+    # Takes a raw comment string and determines what type of tryout token it
+    # represents (description, expectation, etc.). Uses Ruby 3.4+ pattern matching
+    # for clean, maintainable classification logic.
+    #
+    # @param content [String] The comment content (including # prefix)
+    # @param line_number [Integer] 1-based line number for error reporting
+    # @return [Hash] Token hash with :type, :content, :line and other type-specific keys
+    #
+    # @example Valid expectation
+    #   classify_comment_inhousely("#=> 42", 10)
+    #   # => { type: :expectation, content: "42", line: 9, ast: <Prism::Node> }
+    #
+    # @example Malformed expectation (triggers warning)
+    #   classify_comment_inhousely("#=INVALID> 42", 10)
+    #   # => { type: :malformed_expectation, syntax: "INVALID", content: "42", line: 9 }
+    #   # Also adds warning to parser's warning collection
+    #
+    # @example Test description
+    #   classify_comment_inhousely("## Test basic math", 5)
+    #   # => { type: :description, content: "Test basic math", line: 4 }
     def classify_comment_inhousely(content, line_number)
       case content
-      when /^##\s*(.*)$/
+      in /^##\s*(.*)$/ # Test description format: ## description
         { type: :description, content: $1.strip, line: line_number - 1 }
-      when /^#\s*TEST\s*\d*:\s*(.*)$/
+      in /^#\s*TEST\s*\d*:\s*(.*)$/  # rubocop:disable Lint/DuplicateBranch
         { type: :description, content: $1.strip, line: line_number - 1 }
-      when /^#\s*=!>\s*(.*)$/
+      in /^#\s*=!>\s*(.*)$/ # Exception expectation
         { type: :exception_expectation, content: $1.strip, line: line_number - 1, ast: parse_expectation($1.strip) }
-      when /^#\s*=<>\s*(.*)$/
+      in /^#\s*=<>\s*(.*)$/ # Intentional failure expectation
         { type: :intentional_failure_expectation, content: $1.strip, line: line_number - 1, ast: parse_expectation($1.strip) }
-      when /^#\s*==>\s*(.*)$/
+      in /^#\s*==>\s*(.*)$/ # Boolean true expectation
         { type: :true_expectation, content: $1.strip, line: line_number - 1, ast: parse_expectation($1.strip) }
-      when %r{^#\s*=/=>\s*(.*)$}
+      in %r{^#\s*=/=>\s*(.*)$} # Boolean false expectation
         { type: :false_expectation, content: $1.strip, line: line_number - 1, ast: parse_expectation($1.strip) }
-      when /^#\s*=\|>\s*(.*)$/
+      in /^#\s*=\|>\s*(.*)$/ # Boolean (true or false) expectation
         { type: :boolean_expectation, content: $1.strip, line: line_number - 1, ast: parse_expectation($1.strip) }
-      when /^#\s*=\*>\s*(.*)$/
+      in /^#\s*=\*>\s*(.*)$/ # Non-nil expectation
         { type: :non_nil_expectation, content: $1.strip, line: line_number - 1 }
-      when /^#\s*=:>\s*(.*)$/
+      in /^#\s*=:>\s*(.*)$/ # Result type expectation
         { type: :result_type_expectation, content: $1.strip, line: line_number - 1, ast: parse_expectation($1.strip) }
-      when /^#\s*=~>\s*(.*)$/
+      in /^#\s*=~>\s*(.*)$/ # Regex match expectation
         { type: :regex_match_expectation, content: $1.strip, line: line_number - 1, ast: parse_expectation($1.strip) }
-      when /^#\s*=%>\s*(.*)$/
+      in /^#\s*=%>\s*(.*)$/ # Performance time expectation
         { type: :performance_time_expectation, content: $1.strip, line: line_number - 1, ast: parse_expectation($1.strip) }
-      when /^#\s*=(\d+)>\s*(.*)$/
+      in /^#\s*=(\d+)>\s*(.*)$/ # Output expectation (stdout/stderr with pipe number)
         { type: :output_expectation, content: $2.strip, pipe: $1.to_i, line: line_number - 1, ast: parse_expectation($2.strip) }
-      when /^#\s*=>\s*(.*)$/
+      in /^#\s*=>\s*(.*)$/ # Regular expectation
         { type: :expectation, content: $1.strip, line: line_number - 1, ast: parse_expectation($1.strip) }
-      when /^##\s*=>\s*(.*)$/
+      in /^#\s*=([^>=:!~%*|\/\s]+)>\s*(.*)$/ # Malformed expectation - invalid characters between = and >
+        syntax = $1
+        content_part = $2.strip
+        add_warning(ParserWarning.malformed_expectation(
+          line_number: line_number,
+          syntax: syntax,
+          context: content.strip
+        ))
+        { type: :malformed_expectation, syntax: syntax, content: content_part, line: line_number - 1 }
+      in /^##\s*=>\s*(.*)$/ # Commented out expectation (should be ignored)
         { type: :comment, content: '=>' + $1.strip, line: line_number - 1 }
-      when /^#\s*(.*)$/
+      in content if looks_like_malformed_expectation?(content) # Comprehensive malformed expectation detection
+        detected_syntax = extract_malformed_syntax(content)
+        add_warning(ParserWarning.malformed_expectation(
+          line_number: line_number,
+          syntax: detected_syntax,
+          context: content.strip
+        ))
+        { type: :malformed_expectation, syntax: detected_syntax, content: content.strip, line: line_number - 1 }
+      in /^#\s*(.*)$/ # Single hash comment - potential description
         { type: :potential_description, content: $1.strip, line: line_number - 1 }
-      else
+      else # Unknown comment format
         { type: :comment, content: content.sub(/^#\s*/, ''), line: line_number - 1 }
       end
     end
 
+    # Detect if a comment looks like a malformed expectation attempt
+    # This catches patterns that suggest someone tried to write an expectation
+    # but got the syntax wrong (missing parts, wrong spacing, extra characters, etc.)
+    #
+    # Only flags as malformed if it starts with patterns that look like expectation syntax,
+    # not just any comment that happens to contain equals signs in natural language.
+    def looks_like_malformed_expectation?(content)
+      # Skip if it's already handled by specific patterns above
+      return false if content.match?(/^##\s*/) # Description
+      return false if content.match?(/^#\s*TEST\s*\d*:\s*/) # TEST format
+      return false if content.match?(/^##\s*=>\s*/) # Commented out expectation
+
+      # Only flag as malformed if it looks like an expectation attempt at the start
+      # Patterns that suggest malformed expectation syntax:
+      # - Starts with #= but doesn't match valid patterns
+      # - Has multiple = or > characters in suspicious positions near the start
+      # - Looks like broken expectation syntax (not natural language)
+
+      return true if content.match?(/^#\s*=\s*>/) # "# = >" (spaces in wrong places)
+      return true if content.match?(/^#\s*==+>/) # "# ==> " (wrong number of =)
+      return true if content.match?(/^#\s*=[^=:!~%*|\/>\s][^>]*>/) # "# =X> " (invalid chars between = and >)
+      return true if content.match?(/^#\s*>[^=]/) # "# >something" (starts with >)
+      return true if content.match?(/^#\s*<[^=]/) # "# <something" (starts with <)
+
+      false # Regular comments with = signs in natural language are OK
+    end
+
+    # Extract the malformed syntax portion for warning display
+    def extract_malformed_syntax(content)
+      # Try to identify what the user was attempting to write
+      case content
+      when /^#\s*([=><][^=><]*[=><].*?)(\s|$)/ # Pattern with expectation chars
+        $1.strip
+      when /^#\s*([=><].*?)(\s|$)/ # Simple pattern starting with expectation char
+        $1.strip
+      when /^#\s*(.*?[=><].*?)(\s|$)/ # Pattern containing expectation chars
+        $1.strip
+      else
+        # Fallback: show the part after #
+        content.sub(/^#\s*/, '').split(/\s/).first || 'unknown'
+      end
+    end
+
     # Parser type identification for metadata
     def parser_type
       :enhanced