spec_scout 0.1.0

data/examples/workflows/basic_workflow.md

@@ -0,0 +1,159 @@
+# Basic SpecScout Workflow
+
+This document outlines the recommended workflow for using SpecScout in your development process.
+
+## Setup
+
+1. **Install SpecScout**
+   ```bash
+   # Add to Gemfile
+   gem 'spec_scout'
+   
+   # Install
+   bundle install
+   ```
+
+2. **Configure SpecScout**
+   ```ruby
+   # spec/spec_helper.rb
+   require 'spec_scout'
+   
+   SpecScout.configure do |config|
+     config.enable = true
+     config.use_test_prof = true
+     config.enabled_agents = [:database, :factory, :intent, :risk]
+     config.output_format = :console
+   end
+   ```
+
+## Development Workflow
+
+### Step 1: Run Your Tests Normally
+```bash
+# Run your test suite as usual
+bundle exec rspec spec/models/user_spec.rb
+```
+
+### Step 2: Analyze with SpecScout
+```bash
+# Analyze specific spec file
+bundle exec spec_scout spec/models/user_spec.rb
+
+# Or analyze entire test suite
+bundle exec spec_scout
+```
+
+### Step 3: Review Recommendations
+SpecScout will output recommendations like:
+```
+✔ Spec Scout Recommendation
+
+spec/models/user_spec.rb:42
+
+Summary:
+- Factory :user used `create` (3x)
+- DB inserts: 3, selects: 5
+- Runtime: 150ms
+
+Agent Signals:
+- Database Agent: DB unnecessary (✔ HIGH)
+- Factory Agent: prefer build_stubbed (⚠ MEDIUM)
+- Intent Agent: unit test behavior (✔ HIGH)
+- Risk Agent: safe to optimize (✔ HIGH)
+
+Final Recommendation:
+✔ Replace `create(:user)` with `build_stubbed(:user)`
+Confidence: ✔ HIGH
+```
+
+### Step 4: Apply Recommendations
+Based on the confidence level:
+
+**High Confidence (✔)**: Safe to apply immediately
+```ruby
+# Before
+let(:user) { create(:user) }
+
+# After
+let(:user) { build_stubbed(:user) }
+```
+
+**Medium Confidence (⚠)**: Review and test carefully
+- Apply in development environment first
+- Run full test suite after changes
+- Monitor for any behavioral changes
+
+**Low Confidence (?)**: Manual investigation required
+- Review the reasoning provided
+- Consider the specific test context
+- May require domain knowledge to decide
+
+### Step 5: Verify Changes
+```bash
+# Run tests again to ensure they still pass
+bundle exec rspec spec/models/user_spec.rb
+
+# Check performance improvement
+bundle exec rspec spec/models/user_spec.rb --profile
+```
+
+## Best Practices
+
+### 1. Start Small
+- Begin with high-confidence recommendations
+- Apply changes to one spec file at a time
+- Verify each change before moving to the next
+
+### 2. Understand Your Tests
+- Review the agent reasoning
+- Consider your test's specific requirements
+- Don't blindly apply all recommendations
+
+### 3. Monitor Performance
+- Measure test suite performance before and after changes
+- Use TestProf directly for detailed performance analysis
+- Track improvements over time
+
+### 4. Safety First
+- Always run your full test suite after applying changes
+- Use version control to track changes
+- Consider the risk assessment from the Risk Agent
+
+## Common Scenarios
+
+### Unit Tests
+- High confidence for `build_stubbed` recommendations
+- Focus on Database and Factory agents
+- Usually safe to optimize aggressively
+
+### Integration Tests
+- More conservative approach recommended
+- Pay attention to Intent Agent feedback
+- Database persistence often required
+
+### Controller Tests
+- Mixed signals are common
+- Consider test boundaries carefully
+- May benefit from stubbing external dependencies
+
+### System/Feature Tests
+- Usually require database persistence
+- Focus on factory optimization rather than strategy changes
+- Consider test data setup efficiency
+
+## Troubleshooting
+
+### No Recommendations
+- Ensure TestProf is working: `bundle exec rspec --profile`
+- Check SpecScout configuration
+- Verify agents are enabled
+
+### Unexpected Recommendations
+- Enable debug mode: `SPEC_SCOUT_DEBUG=1`
+- Review agent reasoning
+- Consider test-specific context
+
+### Performance Regression
+- Revert changes and analyze
+- Check for missing test coverage
+- Consider test intent vs. implementation

data/examples/workflows/ci_integration.md

@@ -0,0 +1,372 @@
+# CI Integration Workflow
+
+This document provides guidance for integrating SpecScout into your Continuous Integration pipeline.
+
+## Overview
+
+SpecScout can be integrated into CI to:
+- Automatically identify optimization opportunities
+- Enforce performance standards
+- Generate reports for code review
+- Track test performance over time
+
+## GitHub Actions Integration
+
+### Basic Analysis
+
+```yaml
+name: SpecScout Analysis
+
+on: [push, pull_request]
+
+jobs:
+  spec_scout:
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+        
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 3.1
+          bundler-cache: true
+          
+      - name: Setup database
+        run: |
+          bundle exec rails db:create
+          bundle exec rails db:migrate
+          
+      - name: Run SpecScout Analysis
+        run: |
+          bundle exec spec_scout --output json > spec_scout_results.json
+          
+      - name: Upload SpecScout Results
+        uses: actions/upload-artifact@v3
+        with:
+          name: spec-scout-results
+          path: spec_scout_results.json
+```
+
+### Enforcement Mode
+
+```yaml
+name: SpecScout Enforcement
+
+on: [push, pull_request]
+
+jobs:
+  spec_scout_enforcement:
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+        
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 3.1
+          bundler-cache: true
+          
+      - name: Setup database
+        run: |
+          bundle exec rails db:create
+          bundle exec rails db:migrate
+          
+      - name: Run SpecScout with Enforcement
+        run: |
+          bundle exec spec_scout --enforce --fail-on-high-confidence --output json
+        continue-on-error: true
+        id: spec_scout
+        
+      - name: Process Results
+        if: always()
+        run: |
+          if [ ${{ steps.spec_scout.outcome }} == 'failure' ]; then
+            echo "High confidence optimizations found!"
+            echo "Review SpecScout recommendations before merging."
+            exit 1
+          else
+            echo "No high confidence optimizations found."
+          fi
+```
+
+### Performance Tracking
+
+```yaml
+name: Performance Tracking
+
+on: [push, pull_request]
+
+jobs:
+  performance_tracking:
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+        
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 3.1
+          bundler-cache: true
+          
+      - name: Setup database
+        run: |
+          bundle exec rails db:create
+          bundle exec rails db:migrate
+          
+      - name: Run Tests with Profiling
+        run: |
+          bundle exec rspec --profile > test_profile.txt
+          
+      - name: Run SpecScout Analysis
+        run: |
+          bundle exec spec_scout --output json > spec_scout_results.json
+          
+      - name: Generate Performance Report
+        run: |
+          echo "## SpecScout Performance Analysis" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          
+          # Extract high confidence recommendations
+          HIGH_CONFIDENCE=$(jq -r 'select(.confidence == "high") | .spec_location' spec_scout_results.json)
+          
+          if [ -n "$HIGH_CONFIDENCE" ]; then
+            echo "### High Confidence Optimizations Available:" >> $GITHUB_STEP_SUMMARY
+            echo "$HIGH_CONFIDENCE" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "### No high confidence optimizations found" >> $GITHUB_STEP_SUMMARY
+          fi
+          
+      - name: Upload Results
+        uses: actions/upload-artifact@v3
+        with:
+          name: performance-analysis
+          path: |
+            spec_scout_results.json
+            test_profile.txt
+```
+
+## GitLab CI Integration
+
+```yaml
+stages:
+  - test
+  - analysis
+
+spec_scout_analysis:
+  stage: analysis
+  image: ruby:3.1
+  
+  before_script:
+    - bundle install
+    - bundle exec rails db:create
+    - bundle exec rails db:migrate
+    
+  script:
+    - bundle exec spec_scout --output json > spec_scout_results.json
+    
+  artifacts:
+    reports:
+      junit: spec_scout_results.json
+    paths:
+      - spec_scout_results.json
+    expire_in: 1 week
+    
+  only:
+    - merge_requests
+    - main
+
+spec_scout_enforcement:
+  stage: analysis
+  image: ruby:3.1
+  
+  before_script:
+    - bundle install
+    - bundle exec rails db:create
+    - bundle exec rails db:migrate
+    
+  script:
+    - bundle exec spec_scout --enforce --fail-on-high-confidence
+    
+  allow_failure: false
+  
+  only:
+    - main
+```
+
+## Configuration for CI
+
+### Environment-Specific Configuration
+
+```ruby
+# config/spec_scout.rb
+SpecScout.configure do |config|
+  config.enable = true
+  config.use_test_prof = true
+  
+  if ENV['CI']
+    # CI-specific configuration
+    config.output_format = :json
+    config.enforcement_mode = ENV['SPEC_SCOUT_ENFORCE'] == 'true'
+    config.fail_on_high_confidence = ENV['SPEC_SCOUT_FAIL_ON_HIGH'] == 'true'
+    
+    # Focus on performance-critical agents in CI
+    config.enabled_agents = [:database, :factory]
+  else
+    # Development configuration
+    config.output_format = :console
+    config.enforcement_mode = false
+    config.enabled_agents = [:database, :factory, :intent, :risk]
+  end
+end
+```
+
+### Environment Variables
+
+Set these in your CI environment:
+
+```bash
+# Enable enforcement mode
+SPEC_SCOUT_ENFORCE=true
+
+# Fail on high confidence recommendations
+SPEC_SCOUT_FAIL_ON_HIGH=true
+
+# Enable debug output
+SPEC_SCOUT_DEBUG=true
+
+# Disable SpecScout entirely (for debugging CI issues)
+SPEC_SCOUT_DISABLE=true
+```
+
+## Processing Results
+
+### JSON Output Processing
+
+```bash
+#!/bin/bash
+# process_spec_scout_results.sh
+
+RESULTS_FILE="spec_scout_results.json"
+
+if [ ! -f "$RESULTS_FILE" ]; then
+  echo "No SpecScout results found"
+  exit 0
+fi
+
+# Extract high confidence recommendations
+HIGH_CONFIDENCE=$(jq -r 'select(.confidence == "high")' "$RESULTS_FILE")
+
+if [ -n "$HIGH_CONFIDENCE" ]; then
+  echo "High confidence optimizations found:"
+  echo "$HIGH_CONFIDENCE" | jq -r '.spec_location + ": " + .action'
+  
+  # Fail if enforcement is enabled
+  if [ "$SPEC_SCOUT_ENFORCE" = "true" ]; then
+    exit 1
+  fi
+else
+  echo "No high confidence optimizations found"
+fi
+
+# Generate summary
+TOTAL_RECOMMENDATIONS=$(jq -r 'length' "$RESULTS_FILE")
+echo "Total recommendations: $TOTAL_RECOMMENDATIONS"
+```
+
+### Pull Request Comments
+
+```yaml
+- name: Comment PR with SpecScout Results
+  uses: actions/github-script@v6
+  if: github.event_name == 'pull_request'
+  with:
+    script: |
+      const fs = require('fs');
+      
+      if (!fs.existsSync('spec_scout_results.json')) {
+        return;
+      }
+      
+      const results = JSON.parse(fs.readFileSync('spec_scout_results.json', 'utf8'));
+      
+      if (results.confidence === 'high') {
+        const comment = `## SpecScout Analysis
+        
+        High confidence optimization found in \`${results.spec_location}\`:
+        
+        **Recommendation:** ${results.action}
+        **Confidence:** ${results.confidence}
+        
+        **Reasoning:**
+        ${results.explanation.map(e => `- ${e}`).join('\n')}
+        
+        Consider applying this optimization to improve test performance.`;
+        
+        github.rest.issues.createComment({
+          issue_number: context.issue.number,
+          owner: context.repo.owner,
+          repo: context.repo.repo,
+          body: comment
+        });
+      }
+```
+
+## Best Practices for CI
+
+### 1. Gradual Rollout
+- Start with analysis-only mode
+- Monitor results for several weeks
+- Enable enforcement gradually
+
+### 2. Performance Baselines
+- Track test suite performance over time
+- Set up alerts for performance regressions
+- Use SpecScout data to identify trends
+
+### 3. Team Communication
+- Share SpecScout results in code reviews
+- Document optimization decisions
+- Train team on interpreting results
+
+### 4. Maintenance
+- Regularly review CI configuration
+- Update SpecScout version
+- Monitor for false positives
+
+## Troubleshooting CI Issues
+
+### Common Problems
+
+1. **TestProf not working in CI**
+   - Ensure database is properly set up
+   - Check Rails environment configuration
+   - Verify TestProf dependencies
+
+2. **SpecScout timing out**
+   - Reduce enabled agents
+   - Focus on specific spec files
+   - Increase CI timeout limits
+
+3. **False positives in enforcement**
+   - Review agent configuration
+   - Consider test-specific context
+   - Adjust confidence thresholds
+
+### Debug Commands
+
+```bash
+# Test TestProf integration
+bundle exec rspec --profile
+
+# Test SpecScout with debug output
+SPEC_SCOUT_DEBUG=1 bundle exec spec_scout
+
+# Validate configuration
+bundle exec ruby -e "require 'spec_scout'; puts SpecScout.configuration.to_h"
+```

data/exe/spec_scout

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/spec_scout'
+
+# CLI entry point for SpecScout
+SpecScout::CLI.run(ARGV)

data/lib/spec_scout/agent_result.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module SpecScout
+  VALID_CONFIDENCE_LEVELS = %i[high medium low].freeze
+
+  # Agent output containing recommendation, confidence level, and reasoning
+  AgentResult = Struct.new(
+    :agent_name,    # Symbol: :database, :factory, :intent, :risk
+    :verdict,       # Symbol: :db_unnecessary, :prefer_build_stubbed, etc.
+    :confidence,    # Symbol: :high, :medium, :low
+    :reasoning,     # String: Human-readable explanation
+    :metadata,      # Hash: Additional agent-specific data
+    keyword_init: true
+  ) do
+    def initialize(**args)
+      super
+      self.agent_name ||= :unknown
+      self.verdict ||= :no_verdict
+      self.confidence ||= :low
+      self.reasoning ||= ''
+      self.metadata ||= {}
+    end
+
+    def valid?
+      agent_name.is_a?(Symbol) &&
+        verdict.is_a?(Symbol) &&
+        VALID_CONFIDENCE_LEVELS.include?(confidence) &&
+        reasoning.is_a?(String) &&
+        metadata.is_a?(Hash)
+    end
+
+    def high_confidence?
+      confidence == :high
+    end
+
+    def medium_confidence?
+      confidence == :medium
+    end
+
+    def low_confidence?
+      confidence == :low
+    end
+  end
+end

data/lib/spec_scout/agents/database_agent.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require_relative '../base_agent'
+
+module SpecScout
+  module Agents
+    # Agent that analyzes database usage patterns and identifies unnecessary persistence
+    class DatabaseAgent < BaseAgent
+      # Verdict types for database optimization
+      VERDICTS = {
+        db_unnecessary: :db_unnecessary,
+        db_required: :db_required,
+        db_unclear: :db_unclear
+      }.freeze
+
+      def evaluate
+        return no_database_data_result unless database_operations_present?
+
+        insert_count = profile_data.db[:inserts] || 0
+        select_count = profile_data.db[:selects] || 0
+        total_queries = profile_data.db[:total_queries] || 0
+
+        verdict, confidence, reasoning = analyze_database_usage(
+          insert_count: insert_count,
+          select_count: select_count,
+          total_queries: total_queries
+        )
+
+        create_result(
+          verdict: verdict,
+          confidence: confidence,
+          reasoning: reasoning,
+          metadata: {
+            insert_count: insert_count,
+            select_count: select_count,
+            total_queries: total_queries
+          }
+        )
+      end
+
+      private
+
+      def analyze_database_usage(insert_count:, select_count:, total_queries:)
+        if no_db_writes_and_minimal_reads?(insert_count, select_count)
+          db_unnecessary_minimal_reads_result(select_count)
+        elsif no_db_writes_but_some_reads?(insert_count, select_count)
+          db_unnecessary_some_reads_result(select_count)
+        elsif db_writes_present?(insert_count)
+          db_required_result(insert_count)
+        else
+          db_unclear_result(total_queries)
+        end
+      end
+
+      def no_db_writes_and_minimal_reads?(insert_count, select_count)
+        insert_count.zero? && select_count <= 1
+      end
+
+      def no_db_writes_but_some_reads?(insert_count, select_count)
+        insert_count.zero? && select_count > 1
+      end
+
+      def db_writes_present?(insert_count)
+        insert_count.positive?
+      end
+
+      def db_unnecessary_minimal_reads_result(select_count)
+        [
+          VERDICTS[:db_unnecessary],
+          :high,
+          "No database writes detected and minimal reads (#{select_count}). " \
+          'Consider using build_stubbed or avoiding database persistence.'
+        ]
+      end
+
+      def db_unnecessary_some_reads_result(select_count)
+        [
+          VERDICTS[:db_unnecessary],
+          :medium,
+          "No database writes detected but #{select_count} reads. " \
+          'Database persistence may be unnecessary.'
+        ]
+      end
+
+      def db_required_result(insert_count)
+        [
+          VERDICTS[:db_required],
+          :high,
+          "Database writes detected (#{insert_count} inserts). " \
+          'Database persistence appears necessary.'
+        ]
+      end
+
+      def db_unclear_result(total_queries)
+        [
+          VERDICTS[:db_unclear],
+          :low,
+          "Mixed database usage pattern (#{total_queries} total queries). " \
+          'Unable to determine clear optimization opportunity.'
+        ]
+      end
+
+      def no_database_data_result
+        create_result(
+          verdict: VERDICTS[:db_unclear],
+          confidence: :low,
+          reasoning: 'No database usage data available for analysis.',
+          metadata: { no_data: true }
+        )
+      end
+    end
+  end
+end