spec_scout 0.1.0

data/lib/spec_scout/output_formatter.rb

@@ -0,0 +1,307 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+
+module SpecScout
+  # Formats recommendations and analysis results into human-readable console output
+  # and structured JSON format
+  class OutputFormatter
+    CONFIDENCE_SYMBOLS = {
+      high: '✔',
+      medium: '⚠',
+      low: '?'
+    }.freeze
+
+    ACTION_SYMBOLS = {
+      replace_factory_strategy: '✔',
+      avoid_db_persistence: '✔',
+      optimize_queries: '✔',
+      no_action: '—',
+      review_test_intent: '⚠',
+      assess_risk_factors: '⚠'
+    }.freeze
+
+    def initialize(recommendation, profile_data)
+      @recommendation = recommendation
+      @profile_data = profile_data
+      validate_inputs!
+    end
+
+    # Generate human-readable console output
+    def format_recommendation
+      output = []
+
+      output << format_header
+      output << format_spec_location
+      output << ''
+      output << format_profiling_summary
+      output << ''
+      output << format_agent_opinions
+      output << ''
+      output << format_final_recommendation
+
+      output.join("\n")
+    end
+
+    # Generate structured JSON output
+    def format_json
+      json_data = {
+        spec_location: recommendation.spec_location,
+        action: recommendation.action.to_s,
+        from_value: recommendation.from_value,
+        to_value: recommendation.to_value,
+        confidence: recommendation.confidence.to_s,
+        explanation: recommendation.explanation,
+        agent_results: format_agent_results_json,
+        profile_data: format_profile_data_json,
+        metadata: {
+          timestamp: Time.now.iso8601,
+          spec_scout_version: VERSION
+        }
+      }
+
+      JSON.pretty_generate(json_data)
+    end
+
+    private
+
+    attr_reader :recommendation, :profile_data
+
+    def validate_inputs!
+      unless recommendation.is_a?(Recommendation) && recommendation.valid?
+        raise ArgumentError, 'Invalid recommendation provided'
+      end
+
+      return if profile_data.is_a?(ProfileData) && profile_data.valid?
+
+      raise ArgumentError, 'Invalid profile data provided'
+    end
+
+    def format_header
+      confidence_symbol = CONFIDENCE_SYMBOLS[recommendation.confidence]
+      "#{confidence_symbol} Spec Scout Recommendation"
+    end
+
+    def format_spec_location
+      recommendation.spec_location
+    end
+
+    def format_profiling_summary
+      lines = ['Summary:']
+
+      # Factory usage summary
+      if profile_data.factories.any?
+        factory_summary = format_factory_summary
+        lines << "- #{factory_summary}" if factory_summary
+      end
+
+      # Database usage summary
+      if profile_data.db.any?
+        db_summary = format_db_summary
+        lines << "- #{db_summary}" if db_summary
+      end
+
+      # Runtime summary
+      lines << "- Runtime: #{profile_data.runtime_ms}ms" if profile_data.runtime_ms.positive?
+
+      # Spec type
+      lines << "- Type: #{profile_data.spec_type} spec" if profile_data.spec_type != :unknown
+
+      lines.join("\n")
+    end
+
+    def format_factory_summary
+      return nil unless profile_data.factories.is_a?(Hash) && profile_data.factories.any?
+
+      factory_parts = []
+      profile_data.factories.each do |factory_name, factory_info|
+        next unless factory_info.is_a?(Hash)
+
+        strategy = factory_info[:strategy] || 'unknown'
+        count = factory_info[:count] || 1
+        count_text = count > 1 ? " (#{count}x)" : ''
+        factory_parts << "Factory :#{factory_name} used `#{strategy}`#{count_text}"
+      end
+
+      factory_parts.join(', ')
+    end
+
+    def format_db_summary
+      return nil unless profile_data.db.is_a?(Hash) && profile_data.db.any?
+
+      db_parts = []
+
+      if profile_data.db[:inserts]
+        inserts = profile_data.db[:inserts]
+        db_parts << "DB inserts: #{inserts}"
+      end
+
+      if profile_data.db[:selects]
+        selects = profile_data.db[:selects]
+        db_parts << "selects: #{selects}"
+      end
+
+      if profile_data.db[:total_queries]
+        total = profile_data.db[:total_queries]
+        db_parts << "Total queries: #{total}"
+      end
+
+      db_parts.join(', ')
+    end
+
+    def format_agent_opinions
+      return 'Agent Signals:\n- No agent results available' if recommendation.agent_results.empty?
+
+      lines = ['Agent Signals:']
+
+      recommendation.agent_results.each do |agent_result|
+        agent_line = format_agent_opinion(agent_result)
+        lines << "- #{agent_line}"
+      end
+
+      lines.join("\n")
+    end
+
+    def format_agent_opinion(agent_result)
+      agent_name = humanize_agent_name(agent_result.agent_name)
+      verdict = humanize_verdict(agent_result.verdict)
+      confidence = agent_result.confidence.to_s.upcase
+      confidence_symbol = CONFIDENCE_SYMBOLS[agent_result.confidence]
+
+      "#{agent_name}: #{verdict} (#{confidence_symbol} #{confidence})"
+    end
+
+    def humanize_agent_name(agent_name)
+      case agent_name
+      when :database
+        'Database Agent'
+      when :factory
+        'Factory Agent'
+      when :intent
+        'Intent Agent'
+      when :risk
+        'Risk Agent'
+      else
+        agent_name.to_s.split('_').map(&:capitalize).join(' ')
+      end
+    end
+
+    def humanize_verdict(verdict)
+      case verdict
+      when :db_unnecessary
+        'DB unnecessary'
+      when :db_required
+        'DB required'
+      when :db_unclear
+        'DB usage unclear'
+      when :prefer_build_stubbed
+        'prefer build_stubbed'
+      when :create_required
+        'create required'
+      when :strategy_optimal
+        'strategy optimal'
+      when :unit_test_behavior
+        'unit test behavior'
+      when :integration_test_behavior
+        'integration test behavior'
+      when :intent_unclear
+        'intent unclear'
+      when :safe_to_optimize
+        'safe to optimize'
+      when :potential_side_effects
+        'potential side effects'
+      when :high_risk
+        'high risk detected'
+      when :no_verdict
+        'no verdict'
+      else
+        verdict.to_s.gsub('_', ' ')
+      end
+    end
+
+    def format_final_recommendation
+      lines = ['Final Recommendation:']
+
+      action_symbol = ACTION_SYMBOLS[recommendation.action]
+      action_text = format_action_text
+      confidence_text = format_confidence_text
+
+      lines << "#{action_symbol} #{action_text}"
+      lines << "Confidence: #{confidence_text}"
+
+      # Add explanation if available
+      if recommendation.explanation.any?
+        lines << ''
+        lines << 'Reasoning:'
+        recommendation.explanation.each do |explanation_line|
+          lines << "- #{explanation_line}"
+        end
+      end
+
+      lines.join("\n")
+    end
+
+    def format_action_text
+      case recommendation.action
+      when :replace_factory_strategy
+        if !recommendation.from_value.empty? && !recommendation.to_value.empty?
+          "Replace `#{recommendation.from_value}` with `#{recommendation.to_value}`"
+        else
+          'Replace factory strategy with build_stubbed'
+        end
+      when :avoid_db_persistence
+        if !recommendation.from_value.empty? && !recommendation.to_value.empty?
+          "Change from #{recommendation.from_value} to #{recommendation.to_value}"
+        else
+          'Avoid database persistence - use build_stubbed instead of create'
+        end
+      when :optimize_queries
+        'Optimize database queries'
+      when :review_test_intent
+        'Review test intent and boundaries'
+      when :assess_risk_factors
+        'Assess risk factors before optimizing'
+      when :no_action
+        'No optimization recommended'
+      else
+        humanize_action(recommendation.action)
+      end
+    end
+
+    def humanize_action(action)
+      action.to_s.gsub('_', ' ').split.map(&:capitalize).join(' ')
+    end
+
+    def format_confidence_text
+      confidence_symbol = CONFIDENCE_SYMBOLS[recommendation.confidence]
+      confidence_name = recommendation.confidence.to_s.upcase
+
+      "#{confidence_symbol} #{confidence_name}"
+    end
+
+    def format_agent_results_json
+      recommendation.agent_results.map do |agent_result|
+        {
+          agent_name: agent_result.agent_name.to_s,
+          verdict: agent_result.verdict.to_s,
+          confidence: agent_result.confidence.to_s,
+          reasoning: agent_result.reasoning,
+          metadata: agent_result.metadata
+        }
+      end
+    end
+
+    def format_profile_data_json
+      {
+        example_location: profile_data.example_location,
+        spec_type: profile_data.spec_type.to_s,
+        runtime_ms: profile_data.runtime_ms,
+        factories: profile_data.factories,
+        db: profile_data.db,
+        events: profile_data.events,
+        metadata: profile_data.metadata
+      }
+    end
+  end
+end

data/lib/spec_scout/profile_data.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module SpecScout
+  # Normalized profile data structure containing test execution metrics,
+  # factory usage, and database interactions extracted from TestProf
+  ProfileData = Struct.new(
+    :example_location, # String: "spec/models/user_spec.rb:42"
+    :spec_type,          # Symbol: :model, :controller, :integration
+    :runtime_ms,         # Numeric: 38
+    :factories,          # Hash: { user: { strategy: :create, count: 1 } }
+    :db,                 # Hash: { total_queries: 6, inserts: 1, selects: 5 }
+    :events,             # Hash: EventProf data
+    :metadata,           # Hash: Additional context
+    keyword_init: true
+  ) do
+    def initialize(**args)
+      super
+      self.example_location ||= ''
+      self.spec_type ||= :unknown
+      self.runtime_ms ||= 0
+      self.factories ||= {}
+      self.db ||= {}
+      self.events ||= {}
+      self.metadata ||= {}
+    end
+
+    def valid?
+      example_location.is_a?(String) &&
+        spec_type.is_a?(Symbol) &&
+        runtime_ms.is_a?(Numeric) &&
+        factories.is_a?(Hash) &&
+        db.is_a?(Hash) &&
+        events.is_a?(Hash) &&
+        metadata.is_a?(Hash)
+    end
+  end
+end

data/lib/spec_scout/profile_normalizer.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+module SpecScout
+  # Converts TestProf output formats to ProfileData schema
+  class ProfileNormalizer
+    class NormalizationError < StandardError; end
+
+    def initialize
+      @current_example_location = nil
+    end
+
+    # Convert TestProf output to normalized ProfileData
+    def normalize(testprof_data, example_context = {})
+      validate_input(testprof_data)
+
+      ProfileData.new(
+        example_location: extract_example_location(example_context),
+        spec_type: infer_spec_type(example_context),
+        runtime_ms: extract_runtime(testprof_data, example_context),
+        factories: normalize_factory_data(testprof_data),
+        db: normalize_db_data(testprof_data),
+        events: normalize_event_data(testprof_data),
+        metadata: extract_metadata(testprof_data, example_context)
+      )
+    rescue StandardError => e
+      raise NormalizationError, "Failed to normalize TestProf data: #{e.message}"
+    end
+
+    # Set current example context for normalization
+    def set_example_context(location)
+      @current_example_location = location
+    end
+
+    private
+
+    def validate_input(testprof_data)
+      return if testprof_data.is_a?(Hash)
+
+      raise NormalizationError, "TestProf data must be a Hash, got #{testprof_data.class}"
+    end
+
+    def extract_example_location(example_context)
+      # Try multiple sources for example location
+      location = example_context[:location] ||
+                 example_context[:file_path] ||
+                 @current_example_location ||
+                 ''
+
+      # Ensure location is a string
+      location.to_s
+    end
+
+    def infer_spec_type(example_context)
+      location = extract_example_location(example_context)
+
+      case location
+      when %r{spec/models/}
+        :model
+      when %r{spec/controllers/}
+        :controller
+      when %r{spec/requests/}
+        :request
+      when %r{spec/features/}
+        :feature
+      when %r{spec/integration/}
+        :integration
+      when %r{spec/system/}
+        :system
+      when %r{spec/lib/}
+        :lib
+      when %r{spec/helpers/}
+        :helper
+      when %r{spec/views/}
+        :view
+      else
+        :unknown
+      end
+    end
+
+    def extract_runtime(testprof_data, example_context)
+      # Try to extract runtime from various sources
+      runtime = example_context[:runtime] ||
+                example_context[:duration] ||
+                testprof_data.dig(:metadata, :runtime) ||
+                0
+
+      # Convert to milliseconds if needed
+      case runtime
+      when Numeric
+        runtime < 1 ? (runtime * 1000).round(2) : runtime.round(2)
+      else
+        0
+      end
+    end
+
+    def normalize_factory_data(testprof_data)
+      factory_data = testprof_data[:factory_prof] || {}
+      return {} if factory_data.empty?
+
+      normalized = {}
+
+      # Handle FactoryProf stats format
+      factory_data[:stats]&.each do |factory_name, stats|
+        normalized[factory_name] = {
+          strategy: stats[:strategy] || :unknown,
+          count: stats[:count] || 0,
+          time: stats[:time] || 0.0
+        }
+      end
+
+      # Handle alternative factory data formats
+      factory_data[:factories]&.each do |factory_name, factory_info|
+        normalized[factory_name] = normalize_single_factory(factory_info)
+      end
+
+      normalized
+    end
+
+    def normalize_single_factory(factory_info)
+      case factory_info
+      when Hash
+        {
+          strategy: factory_info[:strategy] || detect_strategy_from_info(factory_info),
+          count: factory_info[:count] || factory_info[:total] || 1,
+          time: factory_info[:time] || factory_info[:duration] || 0.0
+        }
+      when Numeric
+        {
+          strategy: :unknown,
+          count: factory_info,
+          time: 0.0
+        }
+      else
+        {
+          strategy: :unknown,
+          count: 1,
+          time: 0.0
+        }
+      end
+    end
+
+    def detect_strategy_from_info(factory_info)
+      # Try to detect strategy from various indicators
+      if factory_info[:create_count]&.positive?
+        :create
+      elsif factory_info[:build_count]&.positive?
+        :build
+      elsif factory_info[:build_stubbed_count]&.positive?
+        :build_stubbed
+      elsif factory_info[:method]
+        factory_info[:method].to_sym
+      else
+        :unknown
+      end
+    end
+
+    def normalize_db_data(testprof_data)
+      db_data = testprof_data[:db_queries] || {}
+
+      # Provide default structure
+      normalized = {
+        total_queries: 0,
+        inserts: 0,
+        selects: 0,
+        updates: 0,
+        deletes: 0
+      }
+
+      # Merge with actual data if available
+      normalized.merge!(db_data.slice(:total_queries, :inserts, :selects, :updates, :deletes)) if db_data.is_a?(Hash)
+
+      # Ensure all values are numeric
+      normalized.transform_values { |v| v.is_a?(Numeric) ? v : 0 }
+    end
+
+    def normalize_event_data(testprof_data)
+      event_data = testprof_data[:event_prof] || {}
+      return {} unless event_data[:events]
+
+      normalized = {}
+
+      event_data[:events].each do |event_name, event_info|
+        normalized[event_name] = {
+          count: event_info[:count] || 0,
+          time: event_info[:time] || 0.0,
+          examples: normalize_event_examples(event_info[:examples])
+        }
+      end
+
+      normalized
+    end
+
+    def normalize_event_examples(examples)
+      return [] unless examples.is_a?(Array)
+
+      examples.map do |example|
+        case example
+        when Hash
+          example.slice(:sql, :time, :location, :backtrace)
+        when String
+          { sql: example }
+        else
+          {}
+        end
+      end.compact
+    end
+
+    def extract_metadata(testprof_data, example_context)
+      metadata = {}
+
+      # Add TestProf metadata
+      metadata.merge!(testprof_data[:metadata]) if testprof_data[:metadata]
+
+      # Add example context metadata
+      metadata[:example_group] = example_context[:example_group] if example_context[:example_group]
+      metadata[:tags] = example_context[:tags] if example_context[:tags]
+      metadata[:description] = example_context[:description] if example_context[:description]
+
+      # Add normalization timestamp
+      metadata[:normalized_at] = Time.now.strftime('%Y-%m-%dT%H:%M:%S%z')
+
+      # Add any error information
+      if testprof_data[:factory_prof] && testprof_data[:factory_prof][:error]
+        metadata[:factory_prof_error] = testprof_data[:factory_prof][:error]
+      end
+
+      if testprof_data[:event_prof] && testprof_data[:event_prof][:error]
+        metadata[:event_prof_error] = testprof_data[:event_prof][:error]
+      end
+
+      if testprof_data[:db_queries] && testprof_data[:db_queries][:error]
+        metadata[:db_queries_error] = testprof_data[:db_queries][:error]
+      end
+
+      metadata
+    end
+  end
+end

data/lib/spec_scout/recommendation.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module SpecScout
+  # Final recommendation containing action, confidence, and explanation
+  Recommendation = Struct.new(
+    :spec_location,   # String: Location of the spec file
+    :action,          # Symbol: :replace_factory_strategy, :avoid_db_persistence, etc.
+    :from_value,      # String: Current value (e.g., "create(:user)")
+    :to_value,        # String: Recommended value (e.g., "build_stubbed(:user)")
+    :confidence,      # Symbol: :high, :medium, :low
+    :explanation,     # Array: Array of explanation strings
+    :agent_results,   # Array: Array of AgentResult objects
+    keyword_init: true
+  ) do
+    VALID_ACTIONS = %i[
+      replace_factory_strategy
+      avoid_db_persistence
+      optimize_queries
+      no_action
+      review_test_intent
+      assess_risk_factors
+    ].freeze
+
+    def initialize(**args)
+      super
+      self.spec_location ||= ''
+      self.action ||= :no_action
+      self.from_value ||= ''
+      self.to_value ||= ''
+      self.confidence ||= :low
+      self.explanation ||= []
+      self.agent_results ||= []
+    end
+
+    def valid?
+      spec_location.is_a?(String) &&
+        VALID_ACTIONS.include?(action) &&
+        from_value.is_a?(String) &&
+        to_value.is_a?(String) &&
+        %i[high medium low].include?(confidence) &&
+        explanation.is_a?(Array) &&
+        agent_results.is_a?(Array) &&
+        agent_results.all? { |result| result.is_a?(AgentResult) }
+    end
+
+    def actionable?
+      action != :no_action
+    end
+
+    def high_confidence?
+      confidence == :high
+    end
+
+    def medium_confidence?
+      confidence == :medium
+    end
+
+    def low_confidence?
+      confidence == :low
+    end
+  end
+end