noiseless 0.0.0 → 0.2.0

data/lib/noiseless/test_case.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+require "minitest"
+require "async"
+require "set" # rubocop:disable Lint/RedundantRequireStatement
+require_relative "test_helper"
+
+module Noiseless
+  # The Ultimate Search Test Case
+  #
+  # Automatically includes TestHelper and provides seamless VCR integration.
+  # Every test method automatically gets its own VCR cassette.
+  #
+  # Usage:
+  #   class Search::ProductTest < Noiseless::TestCase
+  #     def test_searching_by_name
+  #       # Automatically uses cassette: search/product/searching_by_name
+  #       results = Search::Product.by_name("Ruby").execute
+  #       assert results.any?
+  #     end
+  #
+  #     def test_with_custom_options
+  #       # Override VCR options for this test
+  #       noiseless_cassette(record: :new_episodes) do
+  #         results = Search::Product.featured.execute
+  #         assert results.any?
+  #       end
+  #     end
+  #   end
+  class TestCase < Minitest::Test
+    include Noiseless::TestHelper
+
+    # 🎭 Auto-wrap every test method with VCR cassette
+    def self.method_added(method_name)
+      return unless method_name.to_s.start_with?("test_")
+      return if @__noiseless_wrapped_methods&.include?(method_name)
+
+      # Track wrapped methods to avoid infinite recursion
+      @__noiseless_wrapped_methods ||= Set.new
+      @__noiseless_wrapped_methods << method_name
+
+      # Store original method
+      original_method = instance_method(method_name)
+
+      # Remove original method
+      remove_method(method_name)
+
+      # Define wrapped method
+      define_method(method_name) do
+        # Generate cassette name based on class and method
+        cassette_name = generate_test_cassette_name(method_name)
+
+        # Auto-wrap with VCR cassette, passing the actual test method name
+        noiseless_cassette(cassette_name: cassette_name, test_method: method_name) do
+          original_method.bind_call(self)
+        end
+      end
+
+      super
+    end
+
+    # 🏗️ Test setup and teardown
+    def setup
+      super
+      setup_noiseless_test_environment
+    end
+
+    def teardown
+      cleanup_noiseless_test_environment
+      super
+    end
+
+    private
+
+    def generate_test_cassette_name(method_name)
+      # Extract test class path (e.g., "Search::ProductTest" -> "search/product")
+      class_path = self.class.name
+                       .gsub(/Test$/, "")
+                       .underscore
+                       .gsub("::", "/")
+
+      # Extract method name (e.g., "test_searching_products" -> "searching_products")
+      clean_method_name = method_name.to_s.gsub(/^test_/, "")
+
+      "#{class_path}/#{clean_method_name}"
+    end
+
+    def setup_noiseless_test_environment
+      # Set verbose mode if requested
+      @original_verbose = ENV.fetch("NOISELESS_VERBOSE", nil)
+
+      # Ensure test-friendly configuration
+      configure_test_connections if respond_to?(:configure_test_connections)
+
+      # Print test start info if verbose
+      puts "\n[TEST] Starting: #{self.class.name}##{name}" if verbose_mode?
+    end
+
+    def cleanup_noiseless_test_environment
+      # Restore original verbose setting
+      if @original_verbose
+        ENV["NOISELESS_VERBOSE"] = @original_verbose
+      else
+        ENV.delete("NOISELESS_VERBOSE")
+      end
+
+      # Print test completion info if verbose
+      puts "[PASS] Completed: #{self.class.name}##{name}" if verbose_mode?
+    end
+
+    # Enhanced cassette method with auto-naming
+    def noiseless_cassette(options = {}, **kwargs, &)
+      # Use the provided cassette name or generate one from test context
+      # Parent method (TestHelper#noiseless_cassette) will handle the actual VCR setup
+      super
+    end
+
+    # 🔧 Test-specific configuration helpers
+    def configure_test_connections
+      # Override in subclasses to set up test-specific connections
+      # Example:
+      # Noiseless.configure do |config|
+      #   config.connections_config[:test] = {
+      #     adapter: :elasticsearch,
+      #     hosts: ['http://localhost:9201']
+      #   }
+      # end
+    end
+
+    # Enhanced assertion helpers
+    def assert_search_results(search, expected_count = nil, message = nil)
+      # Noiseless is now 100% async - execute returns Async::Task
+      results = if search.respond_to?(:execute)
+                  task = search.execute
+                  Sync { task.wait }
+                else
+                  search
+                end
+
+      assert results.respond_to?(:size) || results.respond_to?(:count),
+             "Expected search results to be enumerable, got #{results.class}"
+
+      result_count = results.respond_to?(:size) ? results.size : results.count
+
+      if expected_count
+        assert_equal expected_count, result_count,
+                     message || "Expected #{expected_count} results, got #{result_count}"
+      else
+        assert result_count.positive?,
+               message || "Expected search results to not be empty"
+      end
+    end
+
+    def assert_search_empty(search, message = nil)
+      # Noiseless is now 100% async - execute returns Async::Task
+      results = if search.respond_to?(:execute)
+                  task = search.execute
+                  Sync { task.wait }
+                else
+                  search
+                end
+      result_count = results.respond_to?(:size) ? results.size : results.count
+
+      assert_equal 0, result_count,
+                   message || "Expected search results to be empty, got #{result_count}"
+    end
+
+    def assert_search_includes(search, expected_item, message = nil)
+      # Noiseless is now 100% async - execute returns Async::Task
+      results = if search.respond_to?(:execute)
+                  task = search.execute
+                  Sync { task.wait }
+                else
+                  search
+                end
+
+      assert results.respond_to?(:include?) || results.respond_to?(:any?),
+             "Expected search results to be enumerable"
+
+      if results.respond_to?(:include?)
+        assert results.include?(expected_item),
+               message || "Expected search results to include #{expected_item}"
+      else
+        assert results.any?(expected_item),
+               message || "Expected search results to include #{expected_item}"
+      end
+    end
+
+    # 🚀 Performance assertion helpers
+    def assert_search_performance(search, max_duration_ms = 1000)
+      start_time = Time.current
+
+      result = if block_given?
+                 yield
+               elsif search.respond_to?(:execute)
+                 # Noiseless is now 100% async - execute returns Async::Task
+                 task = search.execute
+                 Sync { task.wait }
+               else
+                 search
+               end
+
+      duration_ms = ((Time.current - start_time) * 1000).round(2)
+
+      assert duration_ms <= max_duration_ms,
+             "Expected search to complete within #{max_duration_ms}ms, took #{duration_ms}ms"
+
+      puts "[PERF] Search completed in #{duration_ms}ms (limit: #{max_duration_ms}ms)" if verbose_mode?
+
+      result
+    end
+
+    # 🎯 Data setup helpers
+    class << self
+      def setup_test_data(index_name, records, adapter: :primary)
+        define_method :setup do
+          super()
+          seed_data!(index_name, records, adapter: adapter) unless under_vcr_playback?
+        end
+      end
+
+      def reset_test_indexes(*index_names)
+        define_method :setup do
+          super()
+          index_names.each { |name| reset_index!(name) } unless under_vcr_playback?
+        end
+      end
+    end
+  end
+end

data/lib/noiseless/test_helper.rb

@@ -0,0 +1,295 @@
+# frozen_string_literal: true
+
+require "vcr"
+
+module Noiseless
+  # The Ultimate Search Testing Experience
+  #
+  # Provides automatic VCR cassette management, index reset helpers,
+  # debug utilities, and seamless test integration for Noiseless searches.
+  #
+  # Usage:
+  #   class MySearchTest < Minitest::Test
+  #     include Noiseless::TestHelper
+  #
+  #     def test_searching_products
+  #       noiseless_cassette do
+  #         results = Search::Product.by_name("Ruby").execute
+  #         assert results.any?
+  #       end
+  #     end
+  #   end
+  #
+  # Or even simpler:
+  #   class MySearchTest < Noiseless::TestCase
+  #     def test_searching_products
+  #       results = Search::Product.by_name("Ruby").execute
+  #       assert results.any?
+  #     end
+  #   end
+  module TestHelper
+    def self.included(base)
+      base.extend(ClassMethods)
+      setup_vcr_configuration
+    end
+
+    def self.setup_vcr_configuration
+      return if @vcr_configured
+
+      require "webmock"
+      WebMock.disable_net_connect!(allow_localhost: true)
+
+      VCR.configure do |config|
+        config.cassette_library_dir = "test/cassettes"
+        config.hook_into :webmock
+        config.default_cassette_options = {
+          record: :once,
+          match_requests_on: %i[method uri body]
+        }
+
+        # Allow HTTP connections when no cassette is in use (local only in CI)
+        config.allow_http_connections_when_no_cassette = !ENV["CI"]
+
+        # Ignore localhost and CI service hostname connections for tests
+        config.ignore_hosts "localhost", "127.0.0.1", "0.0.0.0",
+                            "elasticsearch", "opensearch", "typesense", "postgres"
+
+        # Filter sensitive data - disabled for localhost testing
+        # config.filter_sensitive_data('<OPENSEARCH_HOST>') do |interaction|
+        #   uri = URI(interaction.request.uri)
+        #   # Only filter non-localhost hosts to avoid test issues
+        #   uri.host unless %w[localhost 127.0.0.1 0.0.0.0].include?(uri.host)
+        # end
+      end
+
+      @vcr_configured = true
+    end
+
+    # Auto-VCR Integration
+    # Automatically generates cassette names from test class and method
+    def noiseless_cassette(options = {}, **kwargs, &)
+      # Use provided cassette name or generate one
+      cassette_name = kwargs[:cassette_name] || generate_cassette_name(test_method: kwargs[:test_method])
+
+      # Extract VCR options from the hash
+      vcr_options = options.except(:cassette_name, :test_method)
+      vcr_options = default_vcr_options.merge(vcr_options)
+
+      instrument_test_execution(cassette_name) do
+        VCR.use_cassette(cassette_name, vcr_options, &)
+      end
+    end
+
+    # Alternative method name for those who prefer it
+    alias use_noiseless_cassette noiseless_cassette
+
+    # 🔧 Index Management Helpers
+    def reset_index!(index_name, adapter: :primary)
+      return if under_vcr_playback?
+
+      client = Noiseless.connections.client(adapter)
+      client.indices.delete(index: index_name) if client.indices.exists(index: index_name)
+      puts "[RESET] Reset index: #{index_name}" if verbose_mode?
+    rescue StandardError => e
+      warn "[WARN] Failed to reset index #{index_name}: #{e.message}" if verbose_mode?
+    end
+
+    def reset_all_indexes!(adapter: :primary)
+      return if under_vcr_playback?
+
+      # Find all registered search classes
+      search_classes = find_search_classes
+      search_classes.each do |klass|
+        reset_index!(klass.index_name, adapter: adapter) if klass.respond_to?(:index_name) && klass.index_name
+      end
+      puts "[RESET] Reset all indexes (#{search_classes.size} classes)" if verbose_mode?
+    end
+
+    # Data Seeding Helpers
+    def seed_data!(index_name, records, adapter: :primary)
+      return if under_vcr_playback?
+
+      client = Noiseless.connections.client(adapter)
+
+      # Convert records to bulk format
+      bulk_body = records.flat_map.with_index do |record, index|
+        doc_id = record.respond_to?(:id) ? record.id : index
+        [
+          { index: { _index: index_name, _id: doc_id } },
+          record.respond_to?(:to_h) ? record.to_h : record
+        ]
+      end
+
+      response = client.bulk(body: bulk_body)
+
+      # Refresh index to make documents searchable immediately
+      client.indices.refresh(index: index_name)
+
+      puts "[SEED] Seeded #{records.size} records to #{index_name}" if verbose_mode?
+      response
+    rescue StandardError => e
+      warn "[WARN] Failed to seed data to #{index_name}: #{e.message}" if verbose_mode?
+    end
+
+    # Debug Utilities
+    def print_curl(search_or_ast, adapter: :primary)
+      return if under_vcr_playback?
+
+      client = Noiseless.connections.client(adapter)
+      ast = search_or_ast.respond_to?(:to_ast) ? search_or_ast.to_ast : search_or_ast
+
+      # Convert AST to query hash
+      query_hash = client.send(:ast_to_hash, ast)
+      index_name = ast.indexes.first || "unknown_index"
+      host = client.instance_variable_get(:@hosts).first
+
+      # Generate curl command
+      curl_command = build_curl_command(host, index_name, query_hash)
+
+      puts "\n[CURL] Debug cURL Command:"
+      puts "=" * 50
+      puts curl_command
+      puts "=" * 50
+
+      curl_command
+    end
+
+    def print_query(search_or_ast)
+      ast = search_or_ast.respond_to?(:to_ast) ? search_or_ast.to_ast : search_or_ast
+
+      puts "\n[DEBUG] Generated Query AST:"
+      puts "=" * 30
+      puts "Indexes: #{ast.indexes}"
+      puts "Must clauses: #{ast.bool.must.size}"
+      puts "Filter clauses: #{ast.bool.filter.size}"
+      puts "Sort clauses: #{ast.sort.size}"
+      puts "Pagination: #{ast.paginate ? "#{ast.paginate.page}/#{ast.paginate.per_page}" : 'default'}"
+      puts "=" * 30
+    end
+
+    # Test Instrumentation
+    def with_search_instrumentation
+      events = []
+      subscription = ActiveSupport::Notifications.subscribe(/noiseless/) do |name, start, finish, _id, payload|
+        events << {
+          event: name,
+          duration: ((finish - start) * 1000).round(2),
+          payload: payload
+        }
+      end
+
+      result = yield
+
+      if verbose_mode? && events.any?
+        puts "\n[EVENTS] Search Events:"
+        events.each do |event|
+          puts "   #{event[:event]}: #{event[:duration]}ms"
+        end
+      end
+
+      result
+    ensure
+      ActiveSupport::Notifications.unsubscribe(subscription) if subscription
+    end
+
+    private
+
+    # 🏷️ Cassette Name Generation
+    def generate_cassette_name(test_method: nil)
+      # Extract test class path (e.g., "Search::ProductTest" -> "search/product")
+      class_path = self.class.name
+                       .gsub(/Test$/, "")
+                       .underscore
+                       .gsub("::", "/")
+
+      # Use provided test method or find from call stack
+      if test_method
+        method_name = test_method.to_s.gsub(/^test_/, "")
+      else
+        # Extract method name from call stack, looking for test method
+        test_method_name = find_test_method_name
+        method_name = test_method_name.gsub(/^test_/, "") if test_method_name
+
+        # Fallback to caller method if test method not found
+        unless method_name
+          caller_method = caller_locations(1, 1).first.label
+          method_name = caller_method.gsub(/^test_/, "").gsub(/[^a-zA-Z0-9_]/, "_")
+        end
+      end
+
+      "#{class_path}/#{method_name}"
+    end
+
+    def find_test_method_name
+      # Look through call stack for test method
+      caller_locations.each do |location|
+        method_name = location.label
+        return method_name if method_name&.start_with?("test_")
+      end
+      nil
+    end
+
+    def instrument_test_execution(cassette_name, &)
+      start_time = Time.current
+
+      puts "\n[VCR] Running test with cassette: #{cassette_name}" if verbose_mode?
+
+      result = with_search_instrumentation(&)
+
+      if verbose_mode?
+        duration = ((Time.current - start_time) * 1000).round(2)
+        puts "[DONE] Test completed in #{duration}ms"
+      end
+
+      result
+    end
+
+    def build_curl_command(host, index_name, query_hash)
+      json_body = JSON.pretty_generate(query_hash)
+
+      <<~CURL
+        curl -X POST "#{host}/#{index_name}/_search" \\
+             -H "Content-Type: application/json" \\
+             -d '#{json_body}'
+      CURL
+    end
+
+    def find_search_classes
+      # Find all classes that inherit from Noiseless::Model
+      ObjectSpace.each_object(Class).select do |klass|
+        klass < Noiseless::Model
+      rescue StandardError
+        false
+      end
+    end
+
+    def under_vcr_playback?
+      VCR.current_cassette&.recording? == false
+    rescue StandardError
+      false
+    end
+
+    def verbose_mode?
+      ENV["NOISELESS_VERBOSE"] == "true" || ENV["VERBOSE"] == "true"
+    end
+
+    def default_vcr_options
+      {
+        record: :once,
+        match_requests_on: %i[method uri body],
+        allow_unused_http_interactions: false
+      }
+    end
+
+    module ClassMethods
+      # 🎭 Class-level test helpers
+      def reset_all_test_indexes!
+        new.reset_all_indexes!
+      end
+
+      def seed_test_data!(index_name, records, adapter: :primary)
+        new.seed_data!(index_name, records, adapter: adapter)
+      end
+    end
+  end
+end

data/lib/noiseless/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Noiseless
-  VERSION = "0.0.0"
-end
+  VERSION = "0.2.0"
+end

data/lib/noiseless.rb

@@ -1,8 +1,152 @@
 # frozen_string_literal: true
 
-require "noiseless/version"
+require "active_support"
+require "active_support/core_ext"
+require "active_support/notifications"
+require "zeitwerk"
+require "yaml"
+require "erb"
+require "json"
+require "singleton"
+require "async"
+require "async/http/endpoint"
+require "async/http/client"
+require "async/pool"
+require_relative "noiseless/version"
 
 module Noiseless
   class Error < StandardError; end
 
-end
+  # HTTP-level failure from the search backend (non-2xx response).
+  class RequestError < Error
+    attr_reader :status, :error_type
+
+    def initialize(message, status: nil, error_type: nil)
+      super(message)
+      @status = status
+      @error_type = error_type
+    end
+  end
+
+  # Raised when a search query is rejected by the backend
+  # (malformed query, missing index, shard failures).
+  class SearchError < RequestError; end
+
+  class Configuration
+    attr_accessor :connections_config, :default_connection, :default_adapter, :config_path
+
+    def initialize
+      @connections_config = {}
+      @default_connection = :primary
+      @default_adapter = :opensearch
+      @config_path = lambda do
+        if defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+          Rails.root.join("config/noiseless.yml")
+        else
+          File.expand_path("config/noiseless.yml", Dir.pwd)
+        end
+      end
+    end
+  end
+
+  def self.config
+    @config ||= Configuration.new
+  end
+
+  def self.reset_config!
+    @config = Configuration.new
+  end
+
+  def self.load_configuration!
+    path = config.config_path.respond_to?(:call) ? config.config_path.call : config.config_path
+    return unless File.exist?(path)
+
+    # Use Rails config_for if available and using standard config path, otherwise use ActiveSupport's YAML with ERB
+    rails_available = defined?(Rails) && Rails.respond_to?(:application) && Rails.respond_to?(:root) && Rails.respond_to?(:env)
+    standard_path = rails_available ? Rails.root.join("config/noiseless.yml") : nil
+
+    if rails_available && Rails.application && path.to_s == standard_path.to_s
+      # config_for already returns environment-specific config with ERB processed
+      env_config = Rails.application.config_for(:noiseless)
+    else
+      # Use YAML.safe_load for custom config files, with ERB processing
+      file_content = File.read(path)
+      processed_content = ERB.new(file_content).result
+      raw = YAML.safe_load(processed_content, aliases: true)
+      environment = rails_available ? Rails.env.to_s : ENV.fetch("RAILS_ENV", "development")
+      env_config = raw[environment] || {}
+    end
+
+    config.default_connection = env_config["default"].to_sym if env_config && env_config["default"]
+    config.connections_config = ((env_config && env_config["connections"]) || {}).transform_keys(&:to_sym)
+                                                                                 .transform_values { |v| v.transform_keys(&:to_sym) }
+
+    # Register all connections statically from YAML - no runtime registration
+    config.connections_config.each do |name, params|
+      adapter_name = params[:adapter]
+      hosts = params[:hosts] || []
+      connections.register(name, adapter: adapter_name, hosts: hosts)
+    end
+  end
+
+  def self.configure
+    yield(config) if block_given?
+  end
+
+  # Global connection manager instance
+  def self.connections
+    @connections ||= ConnectionManager.new
+  end
+
+  # Setup Zeitwerk autoloader
+  loader = Zeitwerk::Loader.for_gem
+  loader.inflector.inflect("ast" => "AST", "dsl" => "DSL", "open_search" => "OpenSearch",
+                           "cluster_api" => "ClusterAPI", "indices_api" => "IndicesAPI")
+  loader.ignore("#{__dir__}/application_search.rb")
+  loader.ignore("#{__dir__}/noiseless/test_helper.rb")
+  loader.ignore("#{__dir__}/noiseless/test_case.rb")
+  loader.setup
+  loader.eager_load if defined?(Rails) && Rails.respond_to?(:env) && Rails.env.test?
+
+  # Manually require response classes since they're in a subdirectory
+  require_relative "noiseless/response"
+  require_relative "noiseless/response_factory"
+
+  # Global registry instance
+  def self.registry
+    ModelRegistry.instance
+  end
+
+  # Convenience methods
+  def self.register_model(model_class, **options)
+    registry.register(model_class, options)
+  end
+
+  def self.all_models
+    registry.all_models
+  end
+
+  def self.searchable_models
+    registry.searchable_models
+  end
+
+  def self.multi_search(models: nil, indexes: nil, connection: nil, &block)
+    search_instance = MultiSearch.new(
+      models: models,
+      indexes: indexes,
+      connection: connection
+    )
+
+    if block
+      search_instance.search(&block)
+    else
+      search_instance
+    end
+  end
+end
+
+# Load Railtie
+require "noiseless/railtie"
+
+# Test helpers must be manually required in test_helper.rb
+# This prevents VCR LoadError in production environments