tryouts 3.5.1 → 3.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ab0eb9c341b10dd5e505a3f62cc33a19a393cb294aecd756809b19c2484784f1
-  data.tar.gz: cddfd1a827b0ef37a9e69224124f2f696bbd8c2f098edbfce79b563b3017fbcd
+  metadata.gz: 3abd83819eeaeaaa533ccf639c975c295737c0241aaded166bda76e95ae0f127
+  data.tar.gz: 0f75679e487a62ef5be88d75c66f6c508efa7ce0867a42354a9e99aac1ea6142
 SHA512:
-  metadata.gz: 066b7697b04b3501f01a0994e9d10a66c5a94d593bdfa5cb1b618bb1264f228425bd7d8b4d98cf9a555a5e23bbe002f137c943d5195ad4ce972de30f03dfac9c
-  data.tar.gz: 82390327e8da8e35d0c9eaa4557800b09bba76e065704f9d704acab45ab24dd62e97edc7aa54d8104ee50cab31a9dab321c75449386f70243674c8f2d838716a
+  metadata.gz: 7f389b6b637cb53cfeb7bd9d20ecd4e8d1392329ec1ec89b390d1f2eb2e0f43c2fda1d503422819b7694d13d867f81b0fa2a0bf644ab60f75004fc8ce92376ab
+  data.tar.gz: 0f72eef3666c7391e4cdfafa6f619878d04a685f7b77d6339de6f757940649b6c0e54f8581738592941f92beab11001b185da4869382544803c51d4acac5bdf1

data/README.md

@@ -132,18 +132,15 @@ try --agent --agent-limit 1000          # limit output to 1000 tokens
 
 #### Why Not Pipe Test Output Directly to AI?
 
-Raw test output creates several problems when working with AI assistants:
+I mean, you could. If that already works well, you could probably still benefit from an agent that is able to focus on the critical information for the task. And the extra context window space.
 
-- **Token bloat**: Verbose formatting wastes 60-80% of your context window on styling
-- **Signal vs noise**: Important failures get buried in passing test details and framework boilerplate
-- **Inconsistent parsing**: AI struggles with varying output formats across different test runs
-- **Context overflow**: Large test suites exceed AI token limits, truncating critical information
+Raw test output creates problems when working with AI assistants: high token usage with inconsistent parsing across different runs, where the same logical failure might be interpreted differently, making it difficult to reliably produce and analyze results consistently.
 
-#### TOPA: A Better Approach
+#### TOPAZ: A Better Approach
 
-Tryouts' `--agent` mode inspired the development of **TOPA (Test Output Protocol for AI)** - a standardized format optimized for AI analysis. The [tpane](https://github.com/delano/tpane) tool implements this protocol, transforming any test framework's output into structured, token-efficient formats.
+Tryouts' `--agent` mode inspired the development of **TOPAZ (Test Output Protocol for AI Zealots)** - a standardized format optimized for AI analysis. The [tpane](https://github.com/delano/tpane) tool implements this protocol, transforming any test framework's output into structured, token-efficient formats.
 
-Instead of overwhelming AI with raw output, TOPA provides clean semantic data focusing on what actually needs attention - failures, errors, and actionable context.
+Instead of overwhelming AI with raw output, TOPAZ provides clean semantic data focusing on what actually needs attention - failures, errors, and actionable context.
 
 ### Exit Codes
 

data/lib/tryouts/cli/formatters/agent.rb

@@ -4,13 +4,13 @@ require_relative 'token_budget'
 
 class Tryouts
   class CLI
-    # TOPA (Test Output Protocol for AI) Formatter
+    # TOPAZ (Test Output Protocol for AI Zealots) Formatter
     #
     # Language-agnostic test output format designed for LLM context management.
-    # This formatter implements the TOPA v1.0 specification for structured,
+    # This formatter implements the TOPAZ v1.0 specification for structured,
     # token-efficient test result communication.
     #
-    # TOPA Features:
+    # TOPAZ Features:
     # - Language-agnostic field naming (snake_case, hierarchical)
     # - Standardized execution context (runtime, environment, VCS)
     # - Token budget awareness with smart truncation
@@ -27,7 +27,7 @@ class Tryouts
     # - environment: Normalized env vars (ci_system, app_env, etc.)
     # - test_framework: Framework name, isolation mode, parser
     # - execution_flags: Runtime flags in normalized form
-    # - protocol: TOPA version and configuration
+    # - protocol: TOPAZ version and configuration
     # - project: Auto-detected project type
     # - test_discovery: File pattern matching rules
     #
@@ -49,7 +49,7 @@ class Tryouts
         @focus_mode = options[:agent_focus] || :failures
         @collected_files = []
         @current_file_data = nil
-        @total_stats = { files: 0, tests: 0, failures: 0, errors: 0, elapsed: 0 }
+        @total_stats = { files: 0, tests: 0, failures: 0, errors: 0, elapsed_time: 0 }
         @output_rendered = false
         @options = options  # Store all options for execution context display
         @all_warnings = []  # Store warnings globally for execution details
@@ -120,7 +120,7 @@ class Tryouts
         # Always update global totals
         @total_stats[:failures] += failed_count
         @total_stats[:errors] += error_count
-        @total_stats[:elapsed] += elapsed_time if elapsed_time
+        @total_stats[:elapsed_time] += elapsed_time if elapsed_time
 
         # Update per-file data - file_result is called AFTER file_end, so data is in @collected_files
         relative_file_path = relative_path(file_path)
@@ -175,7 +175,7 @@ class Tryouts
           error_count: @collected_files.sum { |f| f[:errors].size },
           successful_files: @collected_files.size - @collected_files.count { |f| f[:failures].any? || f[:errors].any? },
           total_files: @collected_files.size,
-          elapsed_time: @total_stats[:elapsed]
+          elapsed_time: @total_stats[:elapsed_time]
         ) unless @output_rendered
       end
 
@@ -188,7 +188,7 @@ class Tryouts
           errors: error_count,
           successful_files: successful_files,
           total_files: total_files,
-          elapsed: elapsed_time
+          elapsed_time: elapsed_time,
         )
 
         # Now render all collected data
@@ -278,9 +278,11 @@ class Tryouts
       def render_summary_only
         output = []
 
-        # Add execution context header for agent clarity
-        output << render_execution_context
-        output << ""
+        time_str = if @total_stats[:elapsed_time] < 2.0
+          " (#{(@total_stats[:elapsed_time] * 1000).round}ms)"
+        else
+          " (#{@total_stats[:elapsed_time].round(2)}s)"
+        end
 
         # Count failures manually from collected file data (same as other render methods)
         failed_count = @collected_files.sum { |f| f[:failures].size }
@@ -293,13 +295,15 @@ class Tryouts
           details = []
           details << "#{failed_count} failed" if failed_count > 0
           details << "#{error_count} errors" if error_count > 0
-          status_parts << "FAIL: #{issues_count}/#{@total_stats[:tests]} tests (#{details.join(', ')}, #{passed_count} passed)"
+          summary = "#{passed_count} testcases passed, #{failed_count} failed"
+          summary += ", #{error_count} errors" if error_count > 0
+          status_parts << "SUMMARY: #{summary}#{time_str}"
         else
           # Agent doesn't need output in the positive case (i.e. for passing
           # tests). It just fills out the context window.
         end
 
-        status_parts << "(#{format_time(@total_stats[:elapsed])})" if @total_stats[:elapsed]
+        status_parts << "(#{format_time(@total_stats[:elapsed_time])})" if @total_stats[:elapsed_time]
 
         output << status_parts.join(" ")
 
@@ -308,14 +312,14 @@ class Tryouts
 
         files_with_issues = @collected_files.select { |f| f[:failures].any? || f[:errors].any? }
         if files_with_issues.any?
-          output << "Files:"
+          output << "FILES:"
           files_with_issues.each do |file_data|
             issue_count = file_data[:failures].size + file_data[:errors].size
             output << "  #{file_data[:path]}: #{issue_count} issue#{'s' if issue_count != 1}"
           end
         elsif @collected_files.any?
           # Show files that were processed successfully
-          output << "Files:"
+          output << "FILES:"
           @collected_files.each do |file_data|
             # Use the passed count from file_result if available, otherwise calculate
             passed_tests = file_data[:passed] ||
@@ -324,6 +328,10 @@ class Tryouts
           end
         end
 
+        # Add execution context at the end
+        output << ""
+        output << render_execution_context
+
         puts output.join("\n") if output.any?
       end
 
@@ -331,21 +339,29 @@ class Tryouts
         # Only show errors (exceptions), skip assertion failures
         critical_files = @collected_files.select { |f| f[:errors].any? }
 
-        output = []
+        time_str = if @total_stats[:elapsed_time] < 2.0
+          " (#{(@total_stats[:elapsed_time] * 1000).round}ms)"
+        else
+          " (#{@total_stats[:elapsed_time].round(2)}s)"
+        end
 
-        # Add execution context header for agent clarity
-        output << render_execution_context
-        output << ""
+        output = []
 
         if critical_files.empty?
           output << "No critical errors found"
+          # Add execution context at the end
+          output << ""
+          output << render_execution_context
           puts output.join("\n")
           return
         end
 
-        output << "CRITICAL: #{critical_files.size} file#{'s' if critical_files.size != 1} with errors"
+        # Summary first
+        output << "SUMMARY:"
+        output << "#{critical_files.size} file#{'s' if critical_files.size != 1} with critical errors#{time_str}"
         output << ""
 
+        # Error details
         critical_files.each do |file_data|
           unless @budget.has_budget?
             output << "... (truncated due to token limit)"
@@ -367,15 +383,20 @@ class Tryouts
           output << ""
         end
 
+        # Add execution context at the end
+        output << render_execution_context
+
         puts output.join("\n")
       end
 
       def render_full_structured
         output = []
 
-        # Add execution context header for agent clarity
-        output << render_execution_context
-        output << ""
+        time_str = if @total_stats[:elapsed_time] < 2.0
+          " (#{(@total_stats[:elapsed_time] * 1000).round}ms)"
+        else
+          " (#{@total_stats[:elapsed_time].round(2)}s)"
+        end
 
         # Count actual failures from collected data
         failed_count = @collected_files.sum { |f| f[:failures].size }
@@ -383,6 +404,14 @@ class Tryouts
         issues_count = failed_count + error_count
         passed_count = [@total_stats[:tests] - issues_count, 0].max
 
+        # Summary first
+        output << "SUMMARY:"
+        summary = "#{passed_count} testcases passed, #{failed_count} failed"
+        summary += ", #{error_count} errors" if error_count > 0
+        summary += " in #{@total_stats[:files]} files#{time_str}"
+        output << summary
+        output << ""
+
         # Show files with issues only
         files_with_issues = @collected_files.select { |f| f[:failures].any? || f[:errors].any? }
 
@@ -404,13 +433,8 @@ class Tryouts
           output << ""
         end
 
-        # Final summary line
-        summary = "Summary: \n"
-        summary += "#{passed_count} testcases passed, #{failed_count} failed"
-        summary += ", #{error_count} errors" if error_count > 0
-        summary += " in #{@total_stats[:files]} files"
-
-        output << summary
+        # Add execution context at the end
+        output << render_execution_context
 
         puts output.join("\n")
       end
@@ -535,7 +559,7 @@ class Tryouts
 
       def render_execution_context
         context_lines = []
-        context_lines << "EXECUTION_CONTEXT:"
+        context_lines << "CONTEXT:"
 
         # Command that was executed
         if @options[:original_command]
@@ -548,7 +572,7 @@ class Tryouts
 
         # Runtime - compact format
         platform = RUBY_PLATFORM.gsub(/darwin\d+/, 'darwin')  # Simplify darwin25 -> darwin
-        context_lines << "  runtime: ruby #{RUBY_VERSION} (#{platform})"
+        context_lines << "  runtime: ruby #{RUBY_VERSION} (#{platform}); tryouts #{Tryouts::VERSION}"
 
         # Package manager - only if present, compact format
         if defined?(Bundler)
@@ -592,8 +616,8 @@ class Tryouts
           context_lines << "  flags: #{flags.join(', ')}"
         end
 
-        # TOPA protocol - compact
-        context_lines << "  protocol: TOPA v1.0 | focus: #{@focus_mode} | limit: #{@budget.limit}"
+        # TOPAZ protocol - compact
+        context_lines << "  protocol: TOPAZ v0.3 | focus: #{@focus_mode} | limit: #{@budget.limit}"
 
         # File count being tested
         if @collected_files && @collected_files.any?

data/lib/tryouts/cli/opts.rb

@@ -10,20 +10,20 @@ class Tryouts
         Minitest:   Fresh context (each test isolated)
 
       Examples:
-        try test_try.rb                          # Tryouts test runner with shared context
-        try --rspec test_try.rb                  # RSpec with fresh context
-        try --direct --shared-context test_try.rb # Explicit shared context
-        try --generate-rspec test_try.rb         # Output RSpec code only
-        try --inspect test_try.rb                # Inspect file structure and validation
-        try --agent test_try.rb                  # Agent-optimized structured output
-        try --agent --agent-limit 10000 tests/  # Agent mode with 10K token limit
+        try test_try.rb                             # Tryouts test runner with shared context
+        try --rspec test_try.rb                     # RSpec with fresh context
+        try --direct --shared-context test_try.rb   # Explicit shared context
+        try --generate-rspec test_try.rb            # Output RSpec code only
+        try --inspect test_try.rb                   # Inspect file structure and validation
+        try --agent test_try.rb                     # Agent-optimized structured output
+        try --agent --agent-limit 10000 tests/      # Agent mode with 10K token limit
 
       Agent Output Modes:
-        --agent                                  # Structured, token-efficient output
-        --agent-focus summary                    # Show counts and problem files only
-        --agent-focus first-failure              # Show first failure per file
-        --agent-focus critical                   # Show errors/exceptions only
-        --agent-limit 1000                      # Limit output to 1000 tokens
+        --agent                                     # Structured, token-efficient output
+        --agent-focus summary                       # Show counts and problem files only
+        --agent-focus first-failure                 # Show first failure per file
+        --agent-focus critical                      # Show errors/exceptions only
+        --agent-limit 1000                          # Limit output to 1000 tokens
 
       File Naming & Organization:
         Files must end with '_try.rb' or '.try.rb' (e.g., auth_service_try.rb, user_model.try.rb)
@@ -37,7 +37,7 @@ class Tryouts
         #=> true  # this is the expected result
 
       File Structure (3 sections):
-        # Setup section (optional) - runs once before all tests
+        # Setup section (optional) - code before first testcase runs once before all tests
         @shared_var = "available to all test cases"
 
         ## TEST: Feature description
@@ -45,9 +45,9 @@ class Tryouts
         result = some_operation()
         #=> expected_value
 
-        # Teardown section (optional) - runs once after all tests
+        # Teardown section (optional) - code after last testcase runs once after all tests
 
-      Context Guidelines:
+      Execution Context:
         Shared Context (default): Instance variables persist across test cases
           - Use for: Integration testing, stateful scenarios, realistic workflows
           - Caution: Test order matters, state accumulates

data/lib/tryouts/file_processor.rb

@@ -1,6 +1,6 @@
 # lib/tryouts/file_processor.rb
 
-require_relative 'parsers/prism_parser'
+require_relative 'parsers/legacy_parser'
 require_relative 'parsers/enhanced_parser'
 require_relative 'test_executor'
 require_relative 'cli/modes/inspect'
@@ -84,7 +84,7 @@ class Tryouts
       when :enhanced
         EnhancedParser.new(file, options)
       when :prism
-        PrismParser.new(file, options)
+        LegacyParser.new(file, options)
       end
     end
 

data/lib/tryouts/parser_warning.rb

@@ -22,5 +22,15 @@ class Tryouts
         suggestion: "Use explicit '## Description' to clarify test structure"
       )
     end
+
+    def self.malformed_expectation(line_number:, syntax:, context:)
+      new(
+        type: :malformed_expectation,
+        message: "Malformed expectation syntax '#=#{syntax}>' at line #{line_number}",
+        line_number: line_number,
+        context: context,
+        suggestion: "Use valid expectation syntax like #=>, #==>, #=:>, #=!>, etc."
+      )
+    end
   end
 end

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