spec_scout 0.1.0

data/lib/spec_scout/base_agent.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module SpecScout
+  # Abstract base class for all analysis agents
+  class BaseAgent
+    attr_reader :profile_data
+
+    def initialize(profile_data)
+      @profile_data = profile_data
+      validate_profile_data!
+    end
+
+    # Abstract method to be implemented by subclasses
+    # Returns an AgentResult with verdict, confidence, and reasoning
+    def evaluate
+      raise NotImplementedError, 'Subclasses must implement #evaluate'
+    end
+
+    # Agent name for identification
+    def agent_name
+      class_name = self.class.name || 'UnknownAgent'
+      class_name.split('::').last.downcase.gsub('agent', '').to_sym
+    end
+
+    protected
+
+    # Helper method to create AgentResult
+    def create_result(verdict:, confidence:, reasoning:, metadata: {})
+      AgentResult.new(
+        agent_name: agent_name,
+        verdict: verdict,
+        confidence: confidence,
+        reasoning: reasoning,
+        metadata: metadata
+      )
+    end
+
+    # Validate confidence level
+    def validate_confidence(confidence)
+      return if AgentResult::VALID_CONFIDENCE_LEVELS.include?(confidence)
+
+      raise ArgumentError, "Invalid confidence level: #{confidence}"
+    end
+
+    # Check if database operations are present
+    def database_operations_present?
+      return false unless profile_data.db.is_a?(Hash)
+
+      total_queries = profile_data.db[:total_queries] || 0
+      inserts = profile_data.db[:inserts] || 0
+
+      total_queries.positive? || inserts.positive?
+    end
+
+    # Check if factories are present
+    def factories_present?
+      return false unless profile_data.factories.is_a?(Hash)
+
+      profile_data.factories.any?
+    end
+
+    private
+
+    def validate_profile_data!
+      raise ArgumentError, "Expected ProfileData, got #{profile_data.class}" unless profile_data.is_a?(ProfileData)
+
+      return if profile_data.valid?
+
+      raise ArgumentError, 'Invalid ProfileData structure'
+    end
+  end
+end

data/lib/spec_scout/cli.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module SpecScout
+  # Command Line Interface for SpecScout
+  class CLI
+    def self.run(args = ARGV)
+      if args.include?('--version') || args.include?('-v')
+        puts "SpecScout #{VERSION}"
+        exit(0)
+      end
+
+      if args.include?('--help') || args.include?('-h')
+        print_help
+        exit(0)
+      end
+
+      # Parse configuration from CLI args
+      config = parse_args(args)
+
+      # Create and run SpecScout
+      scout = SpecScout.new(config)
+      result = scout.analyze
+
+      # Handle output
+      handle_output(result, config)
+
+      # Exit with appropriate code for CI/enforcement mode
+      exit_code = determine_exit_code(result, config)
+      exit(exit_code) if exit_code > 0
+
+      result
+    rescue StandardError => e
+      handle_cli_error(e)
+      exit(1)
+    end
+
+    def self.parse_args(args)
+      config = ::SpecScout.configuration.dup
+
+      i = 0
+      while i < args.length
+        case args[i]
+        when '--disable'
+          config.enable = false
+        when '--no-testprof'
+          config.use_test_prof = false
+        when '--enforce'
+          config.enforcement_mode = true
+        when '--fail-on-high-confidence'
+          config.fail_on_high_confidence = true
+        when '--output', '-o'
+          i += 1
+          raise ArgumentError, '--output requires a format (console, json)' unless i < args.length
+
+          config.output_format = args[i]
+
+        when '--enable-agent'
+          i += 1
+          raise ArgumentError, '--enable-agent requires an agent name' unless i < args.length
+
+          config.enable_agent(args[i])
+
+        when '--disable-agent'
+          i += 1
+          raise ArgumentError, '--disable-agent requires an agent name' unless i < args.length
+
+          config.disable_agent(args[i])
+
+        when '--spec'
+          i += 1
+          raise ArgumentError, '--spec requires a spec file path' unless i < args.length
+        # Store spec location in config metadata for now
+        # This could be enhanced later if needed
+
+        when /^--/
+          raise ArgumentError, "Unknown option: #{args[i]}"
+        end
+        i += 1
+      end
+
+      config.validate!
+      config
+    end
+
+    def self.handle_output(result, config)
+      return unless result
+
+      if result[:recommendation] && result[:profile_data]
+        formatter = OutputFormatter.new(result[:recommendation], result[:profile_data])
+        output = formatter.format_recommendation
+        puts output
+      elsif result[:disabled]
+        puts 'SpecScout is disabled' if config.console_output?
+      elsif result[:no_profile_data]
+        puts 'No profile data available - ensure TestProf is properly configured' if config.console_output?
+      elsif result[:no_agents]
+        puts 'No agents produced results' if config.console_output?
+      elsif result[:error]
+        puts "Analysis failed: #{result[:error].message}" if config.console_output?
+      end
+    end
+
+    def self.determine_exit_code(result, config)
+      return 0 unless result
+      return 0 unless config.enforcement_mode?
+      return 0 unless result[:should_fail]
+
+      1 # Fail in enforcement mode with high confidence recommendations
+    end
+
+    def self.handle_cli_error(error)
+      case error
+      when ArgumentError
+        puts "Error: #{error.message}"
+        puts 'Use --help for usage information'
+      else
+        puts "Unexpected error: #{error.message}"
+        puts error.backtrace.join("\n") if ENV['SPEC_SCOUT_DEBUG']
+      end
+    end
+
+    def self.print_help
+      puts <<~HELP
+        SpecScout - Intelligent test optimization advisor
+
+        Usage: spec_scout [options] [spec_file]
+
+        Options:
+          --disable                    Disable SpecScout analysis
+          --no-testprof               Disable TestProf integration
+          --enforce                   Enable enforcement mode (fail on high confidence)
+          --fail-on-high-confidence   Fail on high confidence recommendations
+          --output FORMAT, -o FORMAT  Output format (console, json)
+          --enable-agent AGENT        Enable specific agent (database, factory, intent, risk)
+          --disable-agent AGENT       Disable specific agent
+          --spec SPEC_FILE            Analyze specific spec file
+          --version, -v               Show version
+          --help, -h                  Show this help message
+
+        Agents:
+          database    Analyze database usage patterns
+          factory     Analyze FactoryBot strategy usage
+          intent      Classify test intent and behavior
+          risk        Identify potentially unsafe optimizations
+
+        Examples:
+          spec_scout                           # Run with default settings
+          spec_scout --enforce                 # Enable enforcement mode
+          spec_scout --output json             # JSON output
+          spec_scout --disable-agent risk      # Disable risk agent
+          spec_scout spec/models/user_spec.rb  # Analyze specific spec file
+
+        Environment Variables:
+          SPEC_SCOUT_DEBUG=1          Enable debug output
+      HELP
+    end
+  end
+end

data/lib/spec_scout/configuration.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module SpecScout
+  # Configuration class for Spec Scout settings
+  # Supports enabling/disabling agents selectively, enforcement modes, and backward compatibility
+  class Configuration
+    attr_accessor :enable, :use_test_prof, :fail_on_high_confidence,
+                  :enabled_agents, :output_format, :enforcement_mode,
+                  :auto_apply_enabled, :blocking_mode_enabled
+
+    VALID_OUTPUT_FORMATS = %i[console json].freeze
+    VALID_AGENTS = %i[database factory intent risk].freeze
+
+    def initialize
+      @enable = true
+      @use_test_prof = true
+      @fail_on_high_confidence = false
+      @enabled_agents = VALID_AGENTS.dup
+      @output_format = :console
+      @enforcement_mode = false
+      @auto_apply_enabled = false # Safety: never auto-apply by default
+      @blocking_mode_enabled = false # Safety: non-blocking by default
+    end
+
+    def enabled?
+      @enable
+    end
+
+    def test_prof_enabled?
+      @use_test_prof
+    end
+
+    def enforcement_mode?
+      @enforcement_mode
+    end
+
+    def auto_apply_enabled?
+      @auto_apply_enabled
+    end
+
+    def blocking_mode_enabled?
+      @blocking_mode_enabled
+    end
+
+    def agent_enabled?(agent_name)
+      @enabled_agents.include?(agent_name.to_sym)
+    end
+
+    def enable_agent(agent_name)
+      agent_sym = agent_name.to_sym
+      raise ArgumentError, "Unknown agent: #{agent_name}" unless VALID_AGENTS.include?(agent_sym)
+
+      @enabled_agents << agent_sym unless @enabled_agents.include?(agent_sym)
+    end
+
+    def disable_agent(agent_name)
+      @enabled_agents.delete(agent_name.to_sym)
+    end
+
+    def output_format=(format)
+      format_sym = format.to_sym
+      unless VALID_OUTPUT_FORMATS.include?(format_sym)
+        raise ArgumentError, "Invalid output format: #{format}. Valid formats: #{VALID_OUTPUT_FORMATS}"
+      end
+
+      @output_format = format_sym
+    end
+
+    def json_output?
+      @output_format == :json
+    end
+
+    def console_output?
+      @output_format == :console
+    end
+
+    def debug_mode?
+      ENV['SPEC_SCOUT_DEBUG'] == 'true'
+    end
+
+    def validate!
+      unless @enabled_agents.all? { |agent| VALID_AGENTS.include?(agent) }
+        invalid_agents = @enabled_agents - VALID_AGENTS
+        raise ArgumentError, "Invalid agents: #{invalid_agents}. Valid agents: #{VALID_AGENTS}"
+      end
+
+      unless VALID_OUTPUT_FORMATS.include?(@output_format)
+        raise ArgumentError, "Invalid output format: #{@output_format}. Valid formats: #{VALID_OUTPUT_FORMATS}"
+      end
+
+      true
+    end
+
+    def to_h
+      {
+        enable: @enable,
+        use_test_prof: @use_test_prof,
+        fail_on_high_confidence: @fail_on_high_confidence,
+        enabled_agents: @enabled_agents,
+        output_format: @output_format,
+        enforcement_mode: @enforcement_mode,
+        auto_apply_enabled: @auto_apply_enabled,
+        blocking_mode_enabled: @blocking_mode_enabled
+      }
+    end
+
+    # Create a duplicate configuration for CLI argument parsing
+    def dup
+      new_config = self.class.new
+      new_config.enable = @enable
+      new_config.use_test_prof = @use_test_prof
+      new_config.fail_on_high_confidence = @fail_on_high_confidence
+      new_config.enabled_agents = @enabled_agents.dup
+      new_config.output_format = @output_format
+      new_config.enforcement_mode = @enforcement_mode
+      new_config.auto_apply_enabled = @auto_apply_enabled
+      new_config.blocking_mode_enabled = @blocking_mode_enabled
+      new_config
+    end
+
+    # Merge configuration from hash (for backward compatibility)
+    def merge!(options = {})
+      options.each do |key, value|
+        case key.to_sym
+        when :enable
+          @enable = value
+        when :use_test_prof
+          @use_test_prof = value
+        when :fail_on_high_confidence
+          @fail_on_high_confidence = value
+        when :enabled_agents
+          @enabled_agents = Array(value).map(&:to_sym)
+        when :output_format
+          self.output_format = value
+        when :enforcement_mode
+          @enforcement_mode = value
+        when :auto_apply_enabled
+          @auto_apply_enabled = value
+        when :blocking_mode_enabled
+          @blocking_mode_enabled = value
+        end
+      end
+      validate!
+      self
+    end
+
+    # Check if enforcement should fail on high confidence
+    def should_fail_on_high_confidence?
+      @enforcement_mode && @fail_on_high_confidence
+    end
+
+    # Gracefully handle disabled TestProf integration
+    def graceful_testprof_disable
+      return self if @use_test_prof
+
+      # When TestProf is disabled, we can still run agents on mock data
+      # This maintains backward compatibility
+      warn 'TestProf integration disabled - running in analysis-only mode' if @enable
+      self
+    end
+  end
+end