spec_scout 0.1.0

data/examples/configurations/basic_config.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Basic SpecScout configuration for most Rails applications
+# Place this in spec/spec_helper.rb or test/test_helper.rb
+
+require 'spec_scout'
+
+SpecScout.configure do |config|
+  # Enable SpecScout analysis
+  config.enable = true
+
+  # Use TestProf for profiling data
+  config.use_test_prof = true
+
+  # Enable all agents for comprehensive analysis
+  config.enabled_agents = %i[database factory intent risk]
+
+  # Console output for development
+  config.output_format = :console
+
+  # Safety settings (recommended)
+  config.auto_apply_enabled = false
+  config.blocking_mode_enabled = false
+end

data/examples/configurations/ci_config.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# CI-friendly SpecScout configuration
+# Optimized for continuous integration environments
+
+require 'spec_scout'
+
+SpecScout.configure do |config|
+  # Enable SpecScout in CI
+  config.enable = true
+
+  # Use TestProf integration
+  config.use_test_prof = true
+
+  # Enable enforcement mode for CI
+  config.enforcement_mode = true
+  config.fail_on_high_confidence = true
+
+  # Focus on performance-critical agents
+  config.enabled_agents = %i[database factory]
+
+  # JSON output for CI processing
+  config.output_format = :json
+
+  # Safety settings
+  config.auto_apply_enabled = false
+  config.blocking_mode_enabled = false
+end
+
+# Example CI usage:
+# bundle exec spec_scout --enforce --output json > spec_scout_results.json
+#
+# Exit codes:
+# 0 - No high confidence recommendations
+# 1 - High confidence recommendations found (CI should fail)

data/examples/configurations/conservative_config.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# Conservative SpecScout configuration
+# Focuses on safe optimizations and avoids risky changes
+
+require 'spec_scout'
+
+SpecScout.configure do |config|
+  # Enable SpecScout
+  config.enable = true
+
+  # Use TestProf integration
+  config.use_test_prof = true
+
+  # Enable risk agent to identify unsafe optimizations
+  # Disable intent agent to avoid boundary-related recommendations
+  config.enabled_agents = %i[database factory risk]
+
+  # Console output for manual review
+  config.output_format = :console
+
+  # Non-enforcement mode for safety
+  config.enforcement_mode = false
+  config.fail_on_high_confidence = false
+
+  # Safety settings (always recommended)
+  config.auto_apply_enabled = false
+  config.blocking_mode_enabled = false
+end
+
+# This configuration prioritizes safety over optimization speed
+# Recommendations will be conservative and well-validated

data/examples/configurations/development_config.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# Development-focused SpecScout configuration
+# Optimized for local development and debugging
+
+require 'spec_scout'
+
+SpecScout.configure do |config|
+  # Enable SpecScout for development
+  config.enable = true
+
+  # Use TestProf integration
+  config.use_test_prof = true
+
+  # Enable all agents for comprehensive feedback
+  config.enabled_agents = %i[database factory intent risk]
+
+  # Console output for immediate feedback
+  config.output_format = :console
+
+  # Non-enforcement mode for development
+  config.enforcement_mode = false
+  config.fail_on_high_confidence = false
+
+  # Safety settings
+  config.auto_apply_enabled = false
+  config.blocking_mode_enabled = false
+end
+
+# Enable debug mode for development
+ENV['SPEC_SCOUT_DEBUG'] = '1' if Rails.env.development?
+
+# Example development workflow:
+# 1. Run specs: bundle exec rspec spec/models/user_spec.rb
+# 2. Review SpecScout recommendations
+# 3. Apply optimizations manually
+# 4. Re-run specs to verify improvements

data/examples/configurations/performance_focused_config.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# Performance-focused SpecScout configuration
+# Optimized for maximum test suite speed improvements
+
+require 'spec_scout'
+
+SpecScout.configure do |config|
+  # Enable SpecScout
+  config.enable = true
+
+  # Use TestProf integration
+  config.use_test_prof = true
+
+  # Focus on performance-critical agents
+  # Skip risk agent for more aggressive optimizations
+  config.enabled_agents = %i[database factory intent]
+
+  # JSON output for automated processing
+  config.output_format = :json
+
+  # Enable enforcement for performance gains
+  config.enforcement_mode = true
+  config.fail_on_high_confidence = true
+
+  # Safety settings (still recommended)
+  config.auto_apply_enabled = false
+  config.blocking_mode_enabled = false
+end
+
+# This configuration prioritizes performance improvements
+# Use with caution - test thoroughly after applying recommendations
+#
+# Recommended workflow:
+# 1. Run with enforcement to identify high-impact optimizations
+# 2. Apply recommendations in small batches
+# 3. Run full test suite after each batch
+# 4. Monitor for any behavioral changes

data/examples/output_formatter_demo.rb

@@ -0,0 +1,67 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Demo script showing OutputFormatter in action
+require_relative '../lib/spec_scout'
+
+# Create sample profile data
+profile_data = SpecScout::ProfileData.new(
+  example_location: 'spec/models/user_spec.rb:42',
+  spec_type: :model,
+  runtime_ms: 38,
+  factories: { user: { strategy: :create, count: 1 } },
+  db: { total_queries: 6, inserts: 1, selects: 5 },
+  events: {},
+  metadata: {}
+)
+
+# Create sample agent results
+agent_results = [
+  SpecScout::AgentResult.new(
+    agent_name: :database,
+    verdict: :db_unnecessary,
+    confidence: :high,
+    reasoning: 'No database writes detected',
+    metadata: {}
+  ),
+  SpecScout::AgentResult.new(
+    agent_name: :factory,
+    verdict: :prefer_build_stubbed,
+    confidence: :medium,
+    reasoning: 'Factory can use build_stubbed',
+    metadata: {}
+  ),
+  SpecScout::AgentResult.new(
+    agent_name: :intent,
+    verdict: :unit_test_behavior,
+    confidence: :high,
+    reasoning: 'Test behaves like unit test',
+    metadata: {}
+  ),
+  SpecScout::AgentResult.new(
+    agent_name: :risk,
+    verdict: :safe_to_optimize,
+    confidence: :high,
+    reasoning: 'No side effects detected',
+    metadata: {}
+  )
+]
+
+# Create sample recommendation
+recommendation = SpecScout::Recommendation.new(
+  spec_location: 'spec/models/user_spec.rb:42',
+  action: :replace_factory_strategy,
+  from_value: 'create(:user)',
+  to_value: 'build_stubbed(:user)',
+  confidence: :high,
+  explanation: [
+    'Strong agreement supports optimization recommendation',
+    '4 agent(s) agree on optimize_persistence approach',
+    'No risk factors detected'
+  ],
+  agent_results: agent_results
+)
+
+# Format and display the recommendation
+formatter = SpecScout::OutputFormatter.new(recommendation, profile_data)
+puts formatter.format_recommendation

data/examples/sample_outputs/console_output_high_confidence.txt

@@ -0,0 +1,27 @@
+✔ Spec Scout Recommendation
+
+spec/models/user_spec.rb:42
+
+Summary:
+- Factory :user used `create` (3x)
+- Factory :post used `create` (2x)
+- DB inserts: 5, selects: 8
+- Runtime: 245ms
+- Type: model spec
+
+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
+
+Reasoning:
+- No database persistence required for this test
+- Factory creates unnecessary database records
+- Test exhibits unit test behavior patterns
+- No risk factors detected (no after_commit callbacks)
+- Potential performance improvement: ~60% faster execution

data/examples/sample_outputs/console_output_medium_confidence.txt

@@ -0,0 +1,27 @@
+⚠ Spec Scout Recommendation
+
+spec/controllers/users_controller_spec.rb:28
+
+Summary:
+- Factory :user used `create` (1x)
+- Factory :organization used `create` (1x)
+- DB inserts: 2, selects: 4
+- Runtime: 180ms
+- Type: controller spec
+
+Agent Signals:
+- Database Agent: DB unclear (? LOW)
+- Factory Agent: prefer build_stubbed (⚠ MEDIUM)
+- Intent Agent: integration test behavior (⚠ MEDIUM)
+- Risk Agent: potential side effects (⚠ MEDIUM)
+
+Final Recommendation:
+⚠ Consider replacing `create(:user)` with `build_stubbed(:user)`
+Confidence: ⚠ MEDIUM
+
+Reasoning:
+- Mixed signals from database usage analysis
+- Controller specs may benefit from stubbed factories
+- Some integration behavior detected - review test boundaries
+- Potential side effects identified - proceed with caution
+- Manual verification recommended before applying changes

data/examples/sample_outputs/console_output_no_action.txt

@@ -0,0 +1,27 @@
+— Spec Scout Recommendation
+
+spec/integration/user_workflow_spec.rb:15
+
+Summary:
+- Factory :user used `create` (2x)
+- Factory :post used `create` (5x)
+- DB inserts: 7, selects: 12
+- Runtime: 420ms
+- Type: integration spec
+
+Agent Signals:
+- Database Agent: DB required (✔ HIGH)
+- Factory Agent: create required (✔ HIGH)
+- Intent Agent: integration test behavior (✔ HIGH)
+- Risk Agent: safe to optimize (✔ HIGH)
+
+Final Recommendation:
+— No optimization recommended
+Confidence: ✔ HIGH
+
+Reasoning:
+- Database persistence is required for this integration test
+- Factory strategy is appropriate for test type
+- Test correctly exhibits integration behavior
+- Current implementation is optimal for test intent
+- No performance improvements available without changing test scope

data/examples/sample_outputs/console_output_risk_detected.txt

@@ -0,0 +1,27 @@
+⚠ Spec Scout Recommendation
+
+spec/models/payment_spec.rb:67
+
+Summary:
+- Factory :payment used `create` (1x)
+- Factory :user used `create` (1x)
+- DB inserts: 2, selects: 3
+- Runtime: 320ms
+- Type: model spec
+
+Agent Signals:
+- Database Agent: DB unnecessary (⚠ MEDIUM)
+- Factory Agent: prefer build_stubbed (⚠ MEDIUM)
+- Intent Agent: unit test behavior (✔ HIGH)
+- Risk Agent: high risk detected (⚠ HIGH)
+
+Final Recommendation:
+⚠ Assess risk factors before optimizing
+Confidence: ? LOW
+
+Reasoning:
+- after_commit callbacks detected in Payment model
+- Complex callback chain may depend on database persistence
+- Optimization could break callback-dependent functionality
+- Manual review required before applying factory strategy changes
+- Consider testing callback behavior separately if optimization is desired

data/examples/sample_outputs/json_output_high_confidence.json

@@ -0,0 +1,108 @@
+{
+  "spec_location": "spec/models/user_spec.rb:42",
+  "action": "replace_factory_strategy",
+  "from_value": "create(:user)",
+  "to_value": "build_stubbed(:user)",
+  "confidence": "high",
+  "explanation": [
+    "No database persistence required for this test",
+    "Factory creates unnecessary database records",
+    "Test exhibits unit test behavior patterns",
+    "No risk factors detected (no after_commit callbacks)",
+    "Potential performance improvement: ~60% faster execution"
+  ],
+  "agent_results": [
+    {
+      "agent_name": "database",
+      "verdict": "db_unnecessary",
+      "confidence": "high",
+      "reasoning": "No database writes or reloads detected in test execution",
+      "metadata": {
+        "insert_count": 3,
+        "select_count": 8,
+        "reload_detected": false,
+        "transaction_usage": false
+      }
+    },
+    {
+      "agent_name": "factory",
+      "verdict": "prefer_build_stubbed",
+      "confidence": "medium",
+      "reasoning": "Factory usage pattern suggests build_stubbed would be sufficient",
+      "metadata": {
+        "factory_strategies": {
+          "user": "create",
+          "post": "create"
+        },
+        "association_access": false,
+        "persistence_required": false
+      }
+    },
+    {
+      "agent_name": "intent",
+      "verdict": "unit_test_behavior",
+      "confidence": "high",
+      "reasoning": "Test exhibits unit test patterns with isolated model testing",
+      "metadata": {
+        "spec_type": "model",
+        "file_location": "spec/models/",
+        "integration_boundaries": false,
+        "external_dependencies": false
+      }
+    },
+    {
+      "agent_name": "risk",
+      "verdict": "safe_to_optimize",
+      "confidence": "high",
+      "reasoning": "No risk factors detected - safe to apply optimization",
+      "metadata": {
+        "after_commit_callbacks": false,
+        "complex_callbacks": false,
+        "side_effects": false,
+        "external_integrations": false
+      }
+    }
+  ],
+  "profile_data": {
+    "example_location": "spec/models/user_spec.rb:42",
+    "spec_type": "model",
+    "runtime_ms": 245,
+    "factories": {
+      "user": {
+        "strategy": "create",
+        "count": 3
+      },
+      "post": {
+        "strategy": "create",
+        "count": 2
+      }
+    },
+    "db": {
+      "total_queries": 13,
+      "inserts": 5,
+      "selects": 8,
+      "updates": 0,
+      "deletes": 0
+    },
+    "events": {
+      "sql.active_record": {
+        "count": 13,
+        "time": 0.15
+      },
+      "factory_bot.run_factory": {
+        "count": 5,
+        "time": 0.08
+      }
+    },
+    "metadata": {
+      "testprof_version": "1.3.0",
+      "rails_version": "7.0.4"
+    }
+  },
+  "metadata": {
+    "timestamp": "2024-01-15T10:30:00Z",
+    "spec_scout_version": "1.0.0",
+    "analysis_duration_ms": 12,
+    "agents_executed": ["database", "factory", "intent", "risk"]
+  }
+}

data/examples/sample_outputs/json_output_no_action.json

@@ -0,0 +1,108 @@
+{
+  "spec_location": "spec/integration/user_workflow_spec.rb:15",
+  "action": "no_action",
+  "from_value": "",
+  "to_value": "",
+  "confidence": "high",
+  "explanation": [
+    "Database persistence is required for this integration test",
+    "Factory strategy is appropriate for test type",
+    "Test correctly exhibits integration behavior",
+    "Current implementation is optimal for test intent",
+    "No performance improvements available without changing test scope"
+  ],
+  "agent_results": [
+    {
+      "agent_name": "database",
+      "verdict": "db_required",
+      "confidence": "high",
+      "reasoning": "Integration test requires database persistence for proper behavior",
+      "metadata": {
+        "insert_count": 7,
+        "select_count": 12,
+        "reload_detected": true,
+        "transaction_usage": true
+      }
+    },
+    {
+      "agent_name": "factory",
+      "verdict": "create_required",
+      "confidence": "high",
+      "reasoning": "Factory persistence is necessary for integration test workflow",
+      "metadata": {
+        "factory_strategies": {
+          "user": "create",
+          "post": "create"
+        },
+        "association_access": true,
+        "persistence_required": true
+      }
+    },
+    {
+      "agent_name": "intent",
+      "verdict": "integration_test_behavior",
+      "confidence": "high",
+      "reasoning": "Test correctly exhibits integration behavior with multiple system interactions",
+      "metadata": {
+        "spec_type": "integration",
+        "file_location": "spec/integration/",
+        "integration_boundaries": true,
+        "external_dependencies": true
+      }
+    },
+    {
+      "agent_name": "risk",
+      "verdict": "safe_to_optimize",
+      "confidence": "high",
+      "reasoning": "No optimization risks detected, but no optimizations recommended",
+      "metadata": {
+        "after_commit_callbacks": false,
+        "complex_callbacks": false,
+        "side_effects": false,
+        "external_integrations": true
+      }
+    }
+  ],
+  "profile_data": {
+    "example_location": "spec/integration/user_workflow_spec.rb:15",
+    "spec_type": "integration",
+    "runtime_ms": 420,
+    "factories": {
+      "user": {
+        "strategy": "create",
+        "count": 2
+      },
+      "post": {
+        "strategy": "create",
+        "count": 5
+      }
+    },
+    "db": {
+      "total_queries": 19,
+      "inserts": 7,
+      "selects": 12,
+      "updates": 0,
+      "deletes": 0
+    },
+    "events": {
+      "sql.active_record": {
+        "count": 19,
+        "time": 0.28
+      },
+      "factory_bot.run_factory": {
+        "count": 7,
+        "time": 0.12
+      }
+    },
+    "metadata": {
+      "testprof_version": "1.3.0",
+      "rails_version": "7.0.4"
+    }
+  },
+  "metadata": {
+    "timestamp": "2024-01-15T10:32:15Z",
+    "spec_scout_version": "1.0.0",
+    "analysis_duration_ms": 8,
+    "agents_executed": ["database", "factory", "intent", "risk"]
+  }
+}