and_one 0.1.0

data/lib/and_one/association_resolver.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+module AndOne
+  # Resolves table names back to ActiveRecord models and identifies
+  # which association is being N+1 loaded, then suggests a fix.
+  module AssociationResolver
+    module_function
+
+    # Given a table name and a cleaned backtrace, attempt to identify
+    # the model, the parent association, and suggest an includes() fix.
+    def resolve(detection, cleaned_backtrace)
+      table = detection.table_name
+      return nil unless table
+
+      target_model = model_for_table(table)
+      return nil unless target_model
+
+      # Find the originating code location (first app frame in the backtrace)
+      origin_frame = find_origin_frame(cleaned_backtrace)
+
+      # Look for the parent model that has an association to the target
+      suggestion = find_association_suggestion(target_model, detection.sample_query)
+
+      Suggestion.new(
+        target_model: target_model,
+        origin_frame: origin_frame,
+        association_name: suggestion&.dig(:association_name),
+        parent_model: suggestion&.dig(:parent_model),
+        fix_hint: suggestion&.dig(:fix_hint),
+        loading_strategy: suggestion&.dig(:loading_strategy),
+        is_through: suggestion&.dig(:is_through) || false,
+        is_polymorphic: suggestion&.dig(:is_polymorphic) || false
+      )
+    end
+
+    # Maps table name -> AR model class.
+    # Thread-safe: uses a Mutex to protect the shared cache since multiple
+    # Puma threads may resolve associations concurrently.
+    def model_for_table(table_name)
+      @table_model_mutex ||= Mutex.new
+      @table_model_cache ||= {}
+
+      # Fast path: read from cache without lock (safe because we never delete keys,
+      # and Hash#[] under GVL is atomic for existing keys)
+      return @table_model_cache[table_name] if @table_model_cache.key?(table_name)
+
+      @table_model_mutex.synchronize do
+        # Double-check after acquiring lock
+        return @table_model_cache[table_name] if @table_model_cache.key?(table_name)
+
+        model = ActiveRecord::Base.descendants.detect do |klass|
+          klass.table_name == table_name
+        rescue
+          false
+        end
+
+        @table_model_cache[table_name] = model
+        model
+      end
+    end
+
+    # Finds the first backtrace frame that's in the app (not a gem/framework frame)
+    def find_origin_frame(cleaned_backtrace)
+      cleaned_backtrace&.first
+    end
+
+    # Tries to find which association on a parent model points to the target model,
+    # and extracts hints from the WHERE clause about the foreign key.
+    def find_association_suggestion(target_model, sql)
+      # Extract the foreign key column from WHERE clause
+      # e.g., WHERE "comments"."post_id" = ? or WHERE "comments"."post_id" IN (?)
+      foreign_key = extract_foreign_key(sql, target_model.table_name)
+
+      # Also try polymorphic foreign key pattern (e.g., commentable_id)
+      poly_foreign_key = extract_polymorphic_foreign_key(sql, target_model.table_name) unless foreign_key
+
+      effective_key = foreign_key || poly_foreign_key
+
+      # Search all models for an association whose foreign key matches
+      ActiveRecord::Base.descendants.each do |klass|
+        next if klass.abstract_class?
+
+        klass.reflect_on_all_associations.each do |assoc|
+          matched = if effective_key
+            association_matches?(assoc, target_model, effective_key)
+          else
+            # For through associations, foreign key may not be directly visible
+            through_association_matches?(assoc, target_model)
+          end
+
+          next unless matched
+
+          strategy = loading_strategy(sql, assoc.name)
+
+          return {
+            parent_model: klass,
+            association_name: assoc.name,
+            fix_hint: build_fix_hint(klass, assoc.name),
+            loading_strategy: strategy,
+            is_through: assoc.is_a?(ActiveRecord::Reflection::ThroughReflection),
+            is_polymorphic: assoc.respond_to?(:options) && !!assoc.options[:as]
+          }
+        end
+      rescue
+        next
+      end
+
+      nil
+    end
+
+    def through_association_matches?(assoc, target_model)
+      return false unless assoc.is_a?(ActiveRecord::Reflection::ThroughReflection)
+
+      begin
+        assoc.klass == target_model
+      rescue NameError
+        false
+      end
+    end
+
+    def extract_polymorphic_foreign_key(sql, table_name)
+      # Match patterns like: "table"."something_type" = AND "table"."something_id"
+      pattern = /["`]?#{Regexp.escape(table_name)}["`]?\.["`]?(\w+)_type["`]?\s*=/i
+      match = sql.match(pattern)
+      "#{match.captures.first}_id" if match
+    end
+
+    def extract_foreign_key(sql, table_name)
+      # Match patterns like: "table"."column_id" = or "table"."column_id" IN
+      pattern = /["`]?#{Regexp.escape(table_name)}["`]?\.["`]?(\w+_id)["`]?\s*(?:=|IN)/i
+      match = sql.match(pattern)
+      match&.captures&.first
+    end
+
+    def association_matches?(assoc, target_model, foreign_key)
+      begin
+        case assoc
+        when ActiveRecord::Reflection::ThroughReflection
+          # has_many :through — check if the source association points to our target
+          assoc.klass == target_model
+        when ActiveRecord::Reflection::HasManyReflection,
+             ActiveRecord::Reflection::HasOneReflection
+          if assoc.options[:as]
+            # Polymorphic: has_many :comments, as: :commentable
+            # The foreign key is like "commentable_id" and there's a "commentable_type" column
+            poly_fk = "#{assoc.options[:as]}_id"
+            assoc.klass == target_model && poly_fk == foreign_key
+          else
+            assoc.klass == target_model && assoc.foreign_key.to_s == foreign_key
+          end
+        else
+          false
+        end
+      rescue NameError
+        false
+      end
+    end
+
+    def build_fix_hint(parent_model, association_name)
+      "Add `.includes(:#{association_name})` to your #{parent_model.name} query"
+    end
+
+    # Determine the optimal loading strategy based on query patterns
+    def loading_strategy(sql, association_name)
+      # If the query has WHERE conditions on the association table, eager_load
+      # is better because it does a LEFT OUTER JOIN allowing WHERE filtering
+      if sql =~ /\bWHERE\b/i && sql =~ /\bJOIN\b/i
+        :eager_load
+      elsif sql =~ /\bWHERE\b.*\b(?:AND|OR)\b/i
+        # Complex WHERE — eager_load with JOIN is more efficient
+        :eager_load
+      else
+        # Default: preload is generally faster (separate queries, no JOIN overhead)
+        # includes is the safe default that lets Rails choose
+        :includes
+      end
+    end
+  end
+
+  class Suggestion
+    attr_reader :target_model, :origin_frame, :association_name, :parent_model,
+                :fix_hint, :loading_strategy, :is_through, :is_polymorphic
+
+    def initialize(target_model:, origin_frame:, association_name:, parent_model:,
+                   fix_hint:, loading_strategy: nil, is_through: false, is_polymorphic: false)
+      @target_model = target_model
+      @origin_frame = origin_frame
+      @association_name = association_name
+      @parent_model = parent_model
+      @fix_hint = fix_hint
+      @loading_strategy = loading_strategy
+      @is_through = is_through
+      @is_polymorphic = is_polymorphic
+    end
+
+    def actionable?
+      !!@association_name
+    end
+
+    # Suggest strict_loading as an alternative prevention strategy
+    def strict_loading_hint
+      return nil unless actionable? && @parent_model
+
+      assoc_type = if @is_through
+        "has_many :#{@association_name}, through: ..."
+      else
+        "has_many :#{@association_name}"
+      end
+
+      "Or prevent at the model level: `#{assoc_type}, strict_loading: true` in #{@parent_model.name}"
+    end
+
+    # Suggest the optimal loading strategy when it differs from plain .includes
+    def loading_strategy_hint
+      return nil unless actionable? && @loading_strategy
+
+      case @loading_strategy
+      when :eager_load
+        "Consider `.eager_load(:#{@association_name})` instead — your query filters on the association, so a JOIN is more efficient"
+      when :preload
+        "Consider `.preload(:#{@association_name})` — separate queries avoid JOIN overhead for simple loading"
+      else
+        nil # :includes is the default, no extra hint needed
+      end
+    end
+  end
+end

data/lib/and_one/console.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module AndOne
+  # Auto-scans for N+1 queries during `rails console` sessions.
+  # Each console command is wrapped in an N+1 scan, and warnings
+  # are printed inline after the result.
+  #
+  # Activated automatically by the Railtie in development, or manually:
+  #
+  #   AndOne::Console.activate!
+  #
+  # To deactivate:
+  #   AndOne::Console.deactivate!
+  #
+  module Console
+    class << self
+      def activate!
+        return if active?
+
+        @active = true
+        @previous_raise = AndOne.raise_on_detect
+        # Never raise in console — always warn inline
+        AndOne.raise_on_detect = false
+
+        start_scan
+        install_hook
+      end
+
+      def deactivate!
+        return unless active?
+
+        finish_scan
+        remove_hook
+        AndOne.raise_on_detect = @previous_raise
+        @active = false
+      end
+
+      def active?
+        @active == true
+      end
+
+      private
+
+      def start_scan
+        return if AndOne.scanning?
+
+        AndOne.scan # Start without a block — manual finish later
+      end
+
+      def finish_scan
+        AndOne.finish if AndOne.scanning?
+      rescue
+        # Don't let cleanup errors interrupt the console
+        nil
+      end
+
+      # Install an IRB/Pry hook that finishes the current scan after each
+      # command and starts a fresh one.
+      def install_hook
+        if defined?(::IRB)
+          install_irb_hook
+        elsif defined?(::Pry)
+          install_pry_hook
+        end
+      end
+
+      def remove_hook
+        if defined?(::IRB) && @irb_hook_installed
+          remove_irb_hook
+        elsif defined?(::Pry) && @pry_hook_installed
+          remove_pry_hook
+        end
+      end
+
+      def install_irb_hook
+        return if @irb_hook_installed
+
+        @irb_hook_installed = true
+
+        # IRB in Rails 7.1+ uses IRB::Context#evaluate with hooks
+        # We hook into the SIGINT-safe eval output via an around_eval approach
+        if defined?(::IRB::Context)
+          ::IRB::Context.prepend(IrbContextPatch)
+        end
+      end
+
+      def remove_irb_hook
+        @irb_hook_installed = false
+        # The prepend can't be removed, but IrbContextPatch checks active?
+      end
+
+      def install_pry_hook
+        return if @pry_hook_installed
+
+        @pry_hook_installed = true
+
+        ::Pry.hooks.add_hook(:after_eval, :and_one_console) do |result, _pry|
+          AndOne::Console.send(:cycle_scan) if AndOne::Console.active?
+        end
+      end
+
+      def remove_pry_hook
+        if defined?(::Pry) && ::Pry.hooks
+          ::Pry.hooks.delete_hook(:after_eval, :and_one_console)
+        end
+        @pry_hook_installed = false
+      end
+
+      # Finish the current scan (reporting any N+1s), then start a fresh one.
+      def cycle_scan
+        finish_scan
+        start_scan
+      end
+    end
+
+    # Prepended into IRB::Context to hook after each evaluation.
+    module IrbContextPatch
+      def evaluate(...)
+        result = super
+        AndOne::Console.send(:cycle_scan) if AndOne::Console.active?
+        result
+      rescue => e
+        AndOne::Console.send(:cycle_scan) if AndOne::Console.active?
+        raise
+      end
+    end
+  end
+end

data/lib/and_one/detection.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module AndOne
+  # Represents a single N+1 detection: the repeated queries, their call site, and metadata.
+  class Detection
+    attr_reader :queries, :caller_locations, :count, :adapter
+
+    def initialize(queries:, caller_locations:, count:, adapter: nil)
+      @queries = queries
+      @caller_locations = caller_locations
+      @count = count
+      @adapter = adapter
+    end
+
+    # Returns the SQL of the first query as the representative example
+    def sample_query
+      @queries.first
+    end
+
+    # Attempt to extract the table name from the repeated query
+    def table_name
+      @table_name ||= extract_table_name(sample_query)
+    end
+
+    # A stable fingerprint for this detection, based on the query shape and
+    # the target table. Independent of call site so the same N+1 pattern
+    # produces the same fingerprint regardless of where it's triggered.
+    # For location-specific ignoring, use `path:` rules in .and_one_ignore.
+    def fingerprint
+      @fingerprint ||= begin
+        sql_fp = Fingerprint.generate(sample_query)
+        Digest::SHA256.hexdigest("#{sql_fp}:#{table_name}")[0, 12]
+      end
+    end
+
+    # The raw caller strings (before backtrace cleaning)
+    def raw_caller_strings
+      @raw_caller_strings ||= caller_locations.map(&:to_s)
+    end
+
+    # The first frame in the call stack that is application code
+    # (not a gem, not ruby stdlib, not and_one itself)
+    def origin_frame
+      @origin_frame ||= find_origin_frame
+    end
+
+    # The frame where the AR relation/collection was likely loaded or iterated.
+    # This is the best place to add .includes().
+    def fix_location
+      @fix_location ||= find_fix_location
+    end
+
+    private
+
+    def extract_table_name(sql)
+      if sql =~ /\bFROM\s+["`]?(\w+)["`]?/i
+        $1
+      end
+    end
+
+    def find_origin_frame
+      raw_caller_strings.detect { |frame| app_frame?(frame) }
+    end
+
+    # Walk the backtrace looking for the frame that set up the iteration.
+    # In a typical N+1, the stack looks like:
+    #   - AR internals (loading the association)
+    #   - The line calling .to_a / accessing the association (origin_frame)
+    #   - The .each / .map / .find_each iteration
+    #   - The controller/view/job that built the relation
+    #
+    # We want the outermost app frame that's near an AR relation method,
+    # or failing that, the second app frame (the caller OF the origin).
+    def find_fix_location
+      app_frames = raw_caller_strings.select { |f| app_frame?(f) }
+      return nil if app_frames.empty?
+
+      # The first app frame is where the association is accessed (inside the loop).
+      # The second app frame is often where the loop itself is, or the controller action.
+      # If they're on the same file+line, look further up.
+      if app_frames.size >= 2 && app_frames[0] != app_frames[1]
+        app_frames[1]
+      else
+        app_frames.detect { |f| f != app_frames[0] } || app_frames.first
+      end
+    end
+
+    def app_frame?(frame)
+      # Not a gem
+      !frame.include?("/gems/") &&
+        # Not ruby stdlib / core
+        !frame.include?("/ruby/") &&
+        # Not and_one's own lib code
+        !frame.include?("lib/and_one/") &&
+        # Not <internal: or (eval) type frames
+        !frame.start_with?("<internal:") &&
+        !frame.include?("(eval)")
+    end
+  end
+end

data/lib/and_one/detector.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module AndOne
+  # Subscribes to ActiveRecord SQL notifications and detects N+1 query patterns.
+  # Each instance tracks queries for a single request/block scope.
+  class Detector
+    DEFAULT_ALLOW_LIST = [
+      /active_record\/relation.*preload_associations/,
+      /active_record\/validations\/uniqueness/
+    ].freeze
+
+    attr_reader :detections
+
+    def initialize(allow_stack_paths: [], ignore_queries: [], min_n_queries: 2)
+      @allow_stack_paths = allow_stack_paths
+      @ignore_queries = ignore_queries
+      @min_n_queries = min_n_queries
+
+      # location_key => count
+      @query_counter = Hash.new(0)
+      # location_key => [sql, ...]
+      @query_holder = Hash.new { |h, k| h[k] = [] }
+      # location_key => caller_locations
+      @query_callers = {}
+      # location_key => additional metadata from AR notification
+      @query_metadata = {}
+
+      @detections = []
+
+      subscribe
+    end
+
+    def finish
+      unsubscribe
+      analyze
+      @detections
+    end
+
+    private
+
+    def subscribe
+      # IMPORTANT: The notification callback fires on whatever thread triggered the SQL,
+      # NOT necessarily the thread that created this Detector. We must look up the
+      # current thread's detector (via Thread.current) to avoid cross-thread contamination.
+      # We store our object_id so the callback can verify it's writing to the correct instance.
+      detector_id = object_id
+
+      @subscriber = ActiveSupport::Notifications.subscribe("sql.active_record") do |*, payload|
+        next unless AndOne.scanning? && !AndOne.paused?
+
+        # Only record if the current thread's detector is THIS detector.
+        # Under Puma, multiple Detectors may be subscribed simultaneously;
+        # each must only process its own thread's queries.
+        current_detector = Thread.current[:and_one_detector]
+        next unless current_detector&.object_id == detector_id
+
+        sql = payload[:sql]
+        name = payload[:name]
+
+        next if name == "SCHEMA"
+        next if !sql.include?("SELECT")
+        next if payload[:cached]
+        next if current_detector.send(:ignored?, sql)
+
+        current_detector.send(:record_query, sql, payload)
+      end
+    end
+
+    def unsubscribe
+      ActiveSupport::Notifications.unsubscribe(@subscriber) if @subscriber
+      @subscriber = nil
+    end
+
+    def record_query(sql, payload)
+      locations = caller_locations
+      location_key = location_fingerprint(locations)
+
+      @query_counter[location_key] += 1
+      @query_holder[location_key] << sql
+
+      # Only store caller on the second occurrence to save memory
+      if @query_counter[location_key] >= 2
+        @query_callers[location_key] = locations
+        @query_metadata[location_key] ||= {
+          connection_adapter: adapter_name,
+          type_casted_binds: payload[:type_casted_binds]
+        }
+      end
+    end
+
+    def location_fingerprint(locations)
+      # Build a hash from the call stack to group identical call paths
+      key = 0
+      locations.each do |loc|
+        key = key ^ loc.path.hash ^ loc.lineno
+      end
+      key
+    end
+
+    def adapter_name
+      ActiveRecord::Base.connection_db_config.adapter
+    rescue
+      "unknown"
+    end
+
+    def analyze
+      @query_counter.each do |location_key, count|
+        next if count < @min_n_queries
+
+        queries = @query_holder[location_key]
+        callers = @query_callers[location_key]
+        metadata = @query_metadata[location_key] || {}
+
+        next unless callers
+
+        # Group by fingerprint to confirm they're actually the same query shape
+        grouped = queries.group_by { |q| Fingerprint.generate(q) }
+        repeated = grouped.values.select { |group| group.size >= @min_n_queries }
+
+        next if repeated.empty?
+
+        caller_strings = callers.map(&:to_s)
+        all_allow = DEFAULT_ALLOW_LIST + @allow_stack_paths
+        next if caller_strings.any? { |frame| all_allow.any? { |pattern| frame.match?(pattern) } }
+
+        repeated.each do |query_group|
+          @detections << Detection.new(
+            queries: query_group,
+            caller_locations: callers,
+            count: query_group.size,
+            adapter: metadata[:connection_adapter]
+          )
+        end
+      end
+    end
+
+    def ignored?(sql)
+      @ignore_queries.any? { |pattern| pattern === sql }
+    end
+  end
+end