eager_eye 1.3.0 → 1.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b938ac5233658e3dcec2b8e6a45a9f33248673e8a0a615d52dbbdbcb8700a9b9
-  data.tar.gz: dc0dff8a86a8381236e355bc65b00c589483272e3dbef07f9d8053ed2428f452
+  metadata.gz: edf21044e597735154b0b1acdcda9230749bf027e8b8acafe70c6aaa1da22b62
+  data.tar.gz: b7d6b716ff42f9e160c292a54ecf0344027c73e24eae29f6aecd34aae27d60ac
 SHA512:
-  metadata.gz: 30dbbb1acb97020776653f681407ec30de7391ad186f7d6748e3ad29f902d8370b647897641ea7835d4a0974484addc6da84f0053c945d9743e23ec340ab55d6
-  data.tar.gz: 4e20c5b19d82859f8dba12657ebdd8eef8d8ec61b909aedf73a30268d49077bfde6bf1a3252e32393a64c66fb98af69689ad15f62c85d4387bf660764d14c680
+  metadata.gz: 1849caab263614bdb85ed1ddcd15f63ae4199cd978ae56e2c8a690ca0e4c0e4616851f9a09f835d95e61adb457e35d5d07fbb3cb189c6394812f7064901cfaed
+  data.tar.gz: fe737b046298753a2fb9739f26307d46fbe4852a47f2a147fae56169259824dff4ced9f3f4cc3c6a37c58dbaea03785d2a1003d230d6b5c7cba56c4224ad011e

data/CHANGELOG.md

@@ -7,7 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [1.3.0] - 2026-05-20
+## [1.3.1] - 2026-06-12
+
+### Changed — precision (fewer false positives)
+
+Validated against two large production apps (~1,080 hand-checked findings). These
+changes cut false positives by ~53% (339 → 158) with near-zero recall loss
+(5 findings), and lift the trustworthy detectors toward 100% precision.
+
+- **Schema-aware column guard.** New `SchemaParser` reads `db/schema.rb` (found by
+  walking up from the scanned path) to learn every table's real columns. When a
+  receiver's model can't be inferred, a method whose name the schema knows as a
+  column (`comsn_rate`, `vat_rate`, `service_fee_rate`) is no longer mistaken for
+  an association/query method. `loop_association` and `custom_method_query` no
+  longer flag column reads on unresolved receivers.
+- **Per-iteration association dedup.** `loop_association` reports a memoized
+  `belongs_to`/`has_one` read once per iteration instead of on every line — a
+  repeated read hits Rails' instance cache, not the database. Associations used
+  as a query-chain base (`x.assoc.find_by`, `x.assoc.where`) still report each
+  occurrence, since those re-query.
+- **Serializer render-site awareness.** New `SerializerUsageParser` scans render
+  sites (`XxxBlueprint.render*`, AMS `(each_)serializer:`) and records, per
+  serializer + Blueprinter view, which associations are eager-loaded and whether
+  only single records are passed. `serializer_nesting` stays silent when an
+  association is preloaded at every render site of that view, or the serializer
+  is only ever handed single records. It never concludes "safe" for a view it
+  can't see rendered, so genuine N+1s are preserved.
+- **`custom_method_query` refinements.** Skips Enumerable aggregates with a block
+  argument (`relation.sum(&:amount)`), per-batch queries inside
+  `in_batches`/`find_in_batches`, and relation query methods called directly on a
+  single iteration element (a SELECT alias such as `record.ids`, not a query).
+- **`validation_n_plus_one`** ignores saves that skip validations
+  (`save(validate: false)` / `create(..., validate: false)`).
 
 ### Added
 

data/lib/eager_eye/analyzer.rb

@@ -19,18 +19,20 @@ module EagerEye
     }.freeze
 
     DETECTOR_EXTRA_ARGS = {
-      Detectors::LoopAssociation => %i[association_preloads association_names method_queries associations_by_model],
-      Detectors::SerializerNesting => %i[association_names method_queries],
+      Detectors::LoopAssociation => %i[association_preloads association_names method_queries associations_by_model
+                                       all_columns],
+      Detectors::SerializerNesting => %i[association_names method_queries serializer_usage all_columns],
       Detectors::MissingCounterCache => %i[association_names],
       Detectors::DecoratorNPlusOne => %i[association_names method_queries],
-      Detectors::CustomMethodQuery => %i[method_queries associations_by_model],
+      Detectors::CustomMethodQuery => %i[method_queries associations_by_model all_columns],
       Detectors::DelegationNPlusOne => %i[delegation_maps],
       Detectors::ScopeChainNPlusOne => %i[scope_maps],
       Detectors::ValidationNPlusOne => %i[uniqueness_models]
     }.freeze
 
     attr_reader :paths, :issues, :association_preloads, :association_names, :method_queries, :delegation_maps,
-                :scope_maps, :uniqueness_models, :associations_by_model
+                :scope_maps, :uniqueness_models, :associations_by_model, :all_columns, :columns_by_model,
+                :serializer_usage
 
     def initialize(paths: nil)
       @paths = Array(paths || EagerEye.configuration.app_path)
@@ -42,17 +44,42 @@ module EagerEye
       @delegation_maps = {}
       @scope_maps = {}
       @uniqueness_models = Set.new
+      @all_columns = Set.new
+      @columns_by_model = {}
+      @serializer_usage = SerializerUsageParser.new
     end
 
     def run
       @issues = []
+      collect_schema
       collect_model_metadata
+      collect_serializer_usage
       ruby_files.each { |file_path| analyze_file(file_path) }
       @issues
     end
 
     private
 
+    def collect_schema
+      schema = SchemaParser.new
+      return unless schema.parse_from_path(@paths[0])
+
+      @all_columns = schema.all_columns
+      @columns_by_model = schema.columns_by_model
+    end
+
+    # Pre-pass over every analyzed file to learn how serializers are rendered
+    # (eager-loaded associations, single-record vs collection). The detector uses
+    # this to stay silent on associations preloaded at all render sites.
+    def collect_serializer_usage
+      ruby_files.each do |file_path|
+        ast = parse_source(File.read(file_path))
+        @serializer_usage.parse_file(ast) if ast
+      rescue Errno::ENOENT, Errno::EACCES
+        next
+      end
+    end
+
     def collect_model_metadata
       model_files.each do |file_path|
         ast = parse_source(File.read(file_path))

data/lib/eager_eye/detectors/custom_method_query.rb

@@ -20,13 +20,14 @@ module EagerEye
         :custom_method_query
       end
 
-      def detect(ast, file_path, method_queries = {}, associations_by_model = {})
+      def detect(ast, file_path, method_queries = {}, associations_by_model = {}, all_columns = Set.new)
         return [] unless ast
 
         @issues = []
         @file_path = file_path
         @method_queries = method_queries
         @associations_by_model = associations_by_model
+        @all_columns = all_columns
 
         # Process each method def as its own scope so variable models from one
         # method don't bleed into another (e.g. `orders = Order.all` in #index
@@ -195,6 +196,11 @@ module EagerEye
           block_body = node.children[2]
           next unless block_var && block_body
 
+          # `x.in_batches.each { |batch| batch.pluck(...) }` — the block var is a
+          # batch relation and any query on it runs once per batch, which is the
+          # recommended fix for N+1, not a symptom. Skip those iterations.
+          next if batch_iteration?(node.children[0])
+
           model_name = infer_model_from_value(node.children[0])
           check_block_for_query_methods(block_body, block_var, collection_is_array?(node.children[0], definitions))
           check_block_for_model_query_methods(block_body, block_var, model_name)
@@ -243,6 +249,21 @@ module EagerEye
           ITERATION_METHODS.include?(node.children[0].children[1])
       end
 
+      BATCH_METHODS = %i[in_batches find_in_batches].freeze # rubocop:disable Lint/UselessConstantScoping
+
+      # True when the iterated collection comes from `in_batches`/`find_in_batches`
+      # — the block variable is a batch relation, so per-batch queries on it are
+      # the intended batching, not an N+1.
+      def batch_iteration?(node)
+        current = node
+        while current.is_a?(Parser::AST::Node) && current.type == :send
+          return true if BATCH_METHODS.include?(current.children[1])
+
+          current = current.children[0]
+        end
+        false
+      end
+
       def check_block_for_query_methods(node, block_var, is_array_collection = false) # rubocop:disable Style/OptionalBooleanParameter
         return unless node.is_a?(Parser::AST::Node)
 
@@ -255,12 +276,31 @@ module EagerEye
 
         method_name = node.children[1]
         return false unless QUERY_METHODS.include?(method_name)
+        return false if enumerable_form?(node)
+        return false if direct_block_var_receiver?(node, block_var, is_array_collection)
         return false if skip_array_method?(node, block_var, is_array_collection)
         return false if receiver_is_query_chain?(node.children[0])
 
         receiver_chain_starts_with?(node.children[0], block_var)
       end
 
+      # A relation query method called straight on the iteration element
+      # (`s_eod.ids`, `s_eod.pluck`) — with no association in between — is not an
+      # N+1: on a single record those names resolve to a column or a SELECT alias
+      # (e.g. `array_agg(...) AS ids`), not a relation query. The real N+1 shape
+      # is `element.association.query`, where the receiver is a send, not the bare
+      # block var. (When the element is itself a known array, the safe-method path
+      # handles it instead.)
+      def direct_block_var_receiver?(node, block_var, is_array_collection)
+        !is_array_collection && direct_block_var?(node.children[0], block_var)
+      end
+
+      # `relation.sum(&:amount)` / `relation.max(&:x)` run in Ruby over the loaded
+      # records (Enumerable), not as SQL — passing a block argument is the tell.
+      def enumerable_form?(node)
+        node.children[2..].any? { |arg| arg.is_a?(Parser::AST::Node) && arg.type == :block_pass }
+      end
+
       def skip_array_method?(node, block_var, is_array_collection)
         return true if receiver_ends_with_safe_transform_method?(node.children[0])
 
@@ -343,16 +383,27 @@ module EagerEye
         model_name && @associations_by_model&.dig(model_name)&.include?(method)
       end
 
+      # With a known receiver model, only flag a method defined as a query on
+      # THAT model. Without an inferred model the global "some model defines this
+      # query-method" fallback would fire on a same-named DB column (e.g. an
+      # EodItem's `comsn_rate` float that Wallet also exposes as a query method),
+      # so a name the schema knows as a column is never treated as a query.
       def method_defined_as_query?(method, model_name)
         return false unless @method_queries
 
         if model_name
           @method_queries[model_name]&.include?(method) || false
+        elsif known_column?(method)
+          false
         else
           @method_queries.any? { |_model, methods| methods.include?(method) }
         end
       end
 
+      def known_column?(method)
+        @all_columns&.include?(method) || false
+      end
+
       def add_issue(node)
         chain = reconstruct_chain(node.children[0])
         @issues << create_issue(

data/lib/eager_eye/detectors/loop_association.rb

@@ -40,7 +40,7 @@ module EagerEye
       end
 
       def detect(ast, file_path, association_preloads = {}, association_names = Set.new, # rubocop:disable Metrics/ParameterLists
-                 method_queries = {}, associations_by_model = {})
+                 method_queries = {}, associations_by_model = {}, all_columns = Set.new)
         return [] unless ast
 
         @issues = []
@@ -49,6 +49,7 @@ module EagerEye
         @dynamic_associations = association_names
         @method_queries = method_queries
         @associations_by_model = associations_by_model
+        @all_columns = all_columns
 
         # Variable preloads/models leak across methods if tracked globally
         # (e.g. controller#index sets `invoices = Invoice.includes(...)`, then
@@ -472,6 +473,7 @@ module EagerEye
 
       def find_association_calls(node, block_var, file_path, issues, included_associations, model_name, skip_nodes) # rubocop:disable Metrics/ParameterLists
         reported = Set.new
+        @requeried_methods = collect_requeried_methods(node, block_var)
         traverse_ast(node) do |child|
           next if skip_nodes.include?(child.object_id)
 
@@ -495,7 +497,7 @@ module EagerEye
         end
       end
 
-      def reportable_association_call?(node, block_var, reported, included, model_name)
+      def reportable_association_call?(node, block_var, reported, included, model_name) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
         return false unless node.type == :send
 
         receiver = node.children[0]
@@ -503,7 +505,40 @@ module EagerEye
         return false unless receiver&.type == :lvar && receiver.children[0] == block_var
         return false if excluded_method?(method, included, model_name)
 
-        reported.add?("#{node.loc.line}:#{method}")
+        # A plain association read memoizes on the instance, so reading it more
+        # than once in one iteration only queries on the FIRST access — dedup the
+        # repeats. But an association used as a query-chain base
+        # (`x.assoc.find_by`, `x.assoc.where`) re-queries every time, so those
+        # occurrences are each real and are reported per line.
+        if @requeried_methods&.include?(method)
+          reported.add?("#{node.loc.line}:#{method}")
+        else
+          reported.add?(method.to_s)
+        end
+      end
+
+      # Methods M where `block_var.M` is the receiver of a SQL-issuing query
+      # method (`.find_by`, `.where`, `.exists?`, `.count`, …) somewhere in the
+      # block. Those re-query on every call (they bypass the memoized association
+      # cache), so M's accesses must not be deduped. A plain chained association
+      # read (`x.prize.badges`) is not a re-query — `prize` stays memoized.
+      # rubocop:disable Lint/UselessConstantScoping
+      REQUERYING_METHODS = %i[where find_by find_by! exists? find first last take
+                              pluck ids count sum average minimum maximum any? none? many? one?].freeze
+      # rubocop:enable Lint/UselessConstantScoping
+
+      def collect_requeried_methods(block_body, block_var) # rubocop:disable Metrics/CyclomaticComplexity
+        requeried = Set.new
+        traverse_ast(block_body) do |node|
+          next unless node.type == :send && REQUERYING_METHODS.include?(node.children[1])
+
+          inner = node.children[0]
+          next unless inner.is_a?(Parser::AST::Node) && inner.type == :send
+          next unless inner.children[0]&.type == :lvar && inner.children[0].children[0] == block_var
+
+          requeried << inner.children[1]
+        end
+        requeried
       end
 
       def excluded_method?(method, included, model_name)
@@ -514,14 +549,31 @@ module EagerEye
 
       # When we know the iteration variable's model AND have parsed that model's
       # associations, trust that map exclusively — methods not in it are columns
-      # or scalar accessors, not associations. Otherwise fall back to heuristics
-      # (hardcoded common names + globally collected association names).
+      # or scalar accessors, not associations.
+      #
+      # When the model CANNOT be inferred (workers, lib/, service objects, blocks
+      # over params / method return values), fall back to the association-name
+      # heuristic — but never flag a name that the schema says is a real DB
+      # column. A column named like an association (`comsn_rate`, `vat_rate`) is
+      # the single largest false-positive source; the schema lets us exclude it
+      # while still catching genuine association access (`prize_point`, `user`).
       def known_association?(method, model_name)
         if model_name && @associations_by_model&.key?(model_name)
           return @associations_by_model[model_name].include?(method)
         end
 
-        ASSOCIATION_NAMES.include?(method.to_s) || @dynamic_associations.include?(method)
+        # Receiver model unknown: a name the schema knows as a DB column is not
+        # an association access. Some names are BOTH a column and an association
+        # elsewhere (`vat_rate`, `currency`); without the model we can't tell, so
+        # we err toward silence (no false positive) and skip them. Names that are
+        # only ever associations (`prize_point`, `user`) are still flagged.
+        return false if known_column?(method)
+
+        @dynamic_associations.include?(method) || ASSOCIATION_NAMES.include?(method.to_s)
+      end
+
+      def known_column?(method)
+        @all_columns&.include?(method) || false
       end
 
       def reportable_method_query_call?(node, block_var, reported, model_name)
@@ -529,17 +581,21 @@ module EagerEye
         return false if EXCLUDED_METHODS.include?(node.children[1])
         return false unless method_known_to_query?(node.children[1], model_name)
 
-        reported.add?("#{node.loc.line}:#{node.children[1]}")
+        reported.add?("q:#{node.children[1]}")
       end
 
       # When the receiver model is known, only consider methods defined as a
-      # query on THAT model — not any model in the project. Without a known
-      # model, fall back to the global "any model has this method" heuristic.
+      # query on THAT model. Without a known model the global "any model has this
+      # method" heuristic can fire on a same-named DB column (e.g. a `comsn_rate`
+      # float that some other model also exposes as a query method), so a name
+      # the schema knows as a column is never treated as a query method.
       def method_known_to_query?(method, model_name)
         return false unless @method_queries
 
         if model_name
           @method_queries[model_name]&.include?(method) || false
+        elsif known_column?(method)
+          false
         else
           @method_queries.any? { |_, ms| ms.include?(method) }
         end

data/lib/eager_eye/detectors/serializer_nesting.rb

@@ -15,11 +15,14 @@ module EagerEye
         :serializer_nesting
       end
 
-      def detect(ast, file_path, association_names = Set.new, method_queries = {})
+      def detect(ast, file_path, association_names = Set.new, method_queries = {}, serializer_usage = nil, # rubocop:disable Metrics/ParameterLists
+                 all_columns = Set.new)
         return [] unless ast
 
         @dynamic_associations = association_names
         @method_queries = method_queries
+        @serializer_usage = serializer_usage
+        @all_columns = all_columns
         issues = []
         traverse_ast(ast) do |node|
           next unless node.type == :class && serializer_class?(node)
@@ -66,11 +69,33 @@ module EagerEye
         body = class_node.children[2]
         return unless body
 
-        traverse_ast(body) do |node|
-          next unless attribute_block?(node) && node.children[2]
+        serializer = extract_class_name(class_node)
+        walk_with_view(body, nil) do |attr_block, view|
+          find_association_in_block(attr_block.children[2], file_path, issues, serializer, view)
+        end
+      end
+
+      # Walk the class body, tracking the enclosing Blueprinter `view :name do ...
+      # end` so each attribute block is tagged with the view it belongs to (nil =
+      # a base/default field rendered by every view). Yields attribute blocks.
+      def walk_with_view(node, view, &block) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+        return unless node.is_a?(Parser::AST::Node)
 
-          find_association_in_block(node.children[2], file_path, issues)
+        if view_block?(node)
+          inner_view = node.children[0].children[2]&.children&.first
+          node.children[2..].each { |c| walk_with_view(c, inner_view, &block) }
+          return
         end
+
+        yield(node, view) if attribute_block?(node) && node.children[2]
+
+        node.children.each { |c| walk_with_view(c, view, &block) }
+      end
+
+      def view_block?(node)
+        node.type == :block && node.children[0]&.type == :send &&
+          node.children[0].children[1] == :view &&
+          node.children[0].children[2]&.type == :sym
       end
 
       def attribute_block?(node)
@@ -78,7 +103,7 @@ module EagerEye
           ATTRIBUTE_METHODS.include?(node.children[0].children[1])
       end
 
-      def find_association_in_block(block_body, file_path, issues)
+      def find_association_in_block(block_body, file_path, issues, serializer, view)
         storage_lines = collect_active_storage_lines(block_body)
 
         traverse_ast(block_body) do |node|
@@ -88,6 +113,7 @@ module EagerEye
           receiver = node.children[0]
           method_name = node.children[1]
           next unless object_reference?(receiver)
+          next if suppressed?(serializer, view, method_name)
 
           if likely_association?(method_name)
             issues << create_issue(
@@ -107,6 +133,22 @@ module EagerEye
         end
       end
 
+      # Stay silent when the access is provably safe:
+      #   * the name is a plain DB column (not a declared association anywhere), or
+      #   * the render-site index shows that everywhere this serializer/view is
+      #     rendered the association is eager-loaded or only single records are
+      #     passed (so there is no collection to multiply into an N+1).
+      def suppressed?(serializer, view, method_name)
+        return true if column_not_association?(method_name)
+        return false unless @serializer_usage&.known_serializer?(serializer)
+
+        @serializer_usage.safe_access?(serializer, view, method_name)
+      end
+
+      def column_not_association?(method_name)
+        @all_columns&.include?(method_name) && !@dynamic_associations&.include?(method_name)
+      end
+
       def object_reference?(node)
         return false unless node
 

data/lib/eager_eye/detectors/validation_n_plus_one.rb

@@ -72,6 +72,7 @@ module EagerEye
 
       def check_create_call(node)
         return unless CREATE_METHODS.include?(node.children[1])
+        return if validations_skipped?(node)
 
         receiver = node.children[0]
         return unless receiver&.type == :const
@@ -82,6 +83,7 @@ module EagerEye
 
       def check_save_call(node, new_model_vars)
         return unless SAVE_METHODS.include?(node.children[1])
+        return if validations_skipped?(node)
 
         receiver = node.children[0]
         return unless receiver&.type == :lvar
@@ -90,6 +92,29 @@ module EagerEye
         add_issue(node, model_name, node.children[1]) if model_name
       end
 
+      # `save(validate: false)` / `create(..., validate: false)` skip ALL
+      # validations, so the uniqueness SELECT never runs — not an N+1.
+      def validations_skipped?(node)
+        node.children[2..].any? { |arg| hash_with_validate_false?(arg) }
+      end
+
+      def hash_with_validate_false?(arg)
+        return false unless arg.is_a?(Parser::AST::Node) && arg.type == :hash
+
+        arg.children.any? { |pair| validate_false_pair?(pair) }
+      end
+
+      def validate_false_pair?(pair)
+        return false unless pair.type == :pair
+
+        key, value = pair.children
+        key&.type == :sym && key.children[0] == :validate && false_literal?(value)
+      end
+
+      def false_literal?(node)
+        node.is_a?(Parser::AST::Node) && node.type == :false # rubocop:disable Lint/BooleanSymbol
+      end
+
       def model_new_call?(node)
         return false unless node.is_a?(Parser::AST::Node) && node.type == :send
 

data/lib/eager_eye/schema_parser.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "parser/current"
+
+module EagerEye
+  # Parses db/schema.rb to learn the real column names of each table. Columns are
+  # the dominant false-positive source: when a receiver's model can't be inferred,
+  # the name heuristics flag any method whose name collides with an association
+  # name — but a DB column (`comsn_rate`, `vat_rate`, `service_fee_rate`) is never
+  # an association. Knowing the column names lets the detectors disambiguate.
+  #
+  # Schema lookup walks up from the analyzed path so `eager_eye app/` still finds
+  # `<root>/db/schema.rb`. Parsing is AST-based (a `create_table "x" do |t| ... end`
+  # block whose body holds `t.<type> "col"` / `t.column "col"` / `t.references "y"`).
+  class SchemaParser
+    COLUMN_DEFINERS = %i[
+      string text integer bigint float decimal boolean date datetime time timestamp
+      binary json jsonb uuid inet cidr money hstore citext virtual primary_key column
+    ].freeze
+    REFERENCE_DEFINERS = %i[references belongs_to].freeze
+
+    attr_reader :columns_by_table, :all_columns
+
+    def initialize
+      @columns_by_table = {}
+      @all_columns = Set.new
+    end
+
+    # Returns true if a schema was found and parsed.
+    def parse_from_path(start_path)
+      schema = locate_schema(start_path)
+      return false unless schema
+
+      ast = parse(File.read(schema))
+      return false unless ast
+
+      walk(ast)
+      true
+    rescue Errno::ENOENT, Errno::EACCES
+      false
+    end
+
+    # Column names mapped onto the model a table name classifies to
+    # ("eod_items" -> "EodItem"). Used for per-model column resolution.
+    def columns_by_model
+      @columns_by_model ||= @columns_by_table.transform_keys { |table| classify(table) }
+    end
+
+    private
+
+    def locate_schema(start_path)
+      dir = File.expand_path(File.directory?(start_path) ? start_path : File.dirname(start_path))
+      12.times do
+        candidate = File.join(dir, "db", "schema.rb")
+        return candidate if File.file?(candidate)
+
+        parent = File.dirname(dir)
+        break if parent == dir
+
+        dir = parent
+      end
+      nil
+    end
+
+    def parse(source)
+      Parser::CurrentRuby.parse(source)
+    rescue Parser::SyntaxError
+      nil
+    end
+
+    def walk(node)
+      return unless node.is_a?(Parser::AST::Node)
+
+      capture_create_table(node) if create_table_block?(node)
+      node.children.each { |child| walk(child) }
+    end
+
+    def create_table_block?(node)
+      node.type == :block && node.children[0]&.type == :send &&
+        node.children[0].children[1] == :create_table
+    end
+
+    def capture_create_table(block_node)
+      table = string_arg(block_node.children[0])
+      return unless table
+
+      cols = (@columns_by_table[table] ||= Set.new)
+      collect_columns(block_node.children[2], cols)
+    end
+
+    def collect_columns(body, cols)
+      return unless body.is_a?(Parser::AST::Node)
+
+      add_column_from_send(body, cols) if body.type == :send
+      body.children.each { |child| collect_columns(child, cols) }
+    end
+
+    def add_column_from_send(node, cols)
+      method = node.children[1]
+      name = string_arg(node)
+      return unless name
+
+      if COLUMN_DEFINERS.include?(method)
+        register(cols, name)
+      elsif REFERENCE_DEFINERS.include?(method)
+        register(cols, "#{name}_id")
+      end
+    end
+
+    def register(cols, name)
+      sym = name.to_sym
+      cols << sym
+      @all_columns << sym
+    end
+
+    def string_arg(node)
+      return unless node.is_a?(Parser::AST::Node)
+
+      node.children[2..]&.find { |a| a.is_a?(Parser::AST::Node) && a.type == :str }&.children&.first
+    end
+
+    def classify(table)
+      base = table.to_s
+      singular = base.respond_to?(:singularize) ? base.singularize : base.sub(/s\z/, "")
+      singular.split("_").map(&:capitalize).join
+    end
+  end
+end

data/lib/eager_eye/serializer_usage_parser.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+require "parser/current"
+
+module EagerEye
+  # Serializers are the worst false-positive source because the detector sees the
+  # serializer class in isolation: it cannot tell whether an association it flags
+  # is actually eager-loaded by the controller that renders it, nor whether the
+  # serializer is only ever handed a single record (no collection => no N+1).
+  #
+  # This parser scans the whole app for render sites — `XxxBlueprint.render*(arg,
+  # view: :v)`, AMS `render json: arg, (each_)serializer: XxxSerializer` — and,
+  # per (serializer, view), records:
+  #   * preloaded_per_site : the associations eager-loaded on `arg` at each site
+  #   * any_collection      : was `arg` ever a collection (vs a single record)?
+  # An association preloaded at EVERY site, or a serializer only ever fed single
+  # records, cannot cause an N+1 — letting the detector stay silent there.
+  class SerializerUsageParser
+    PRELOAD_METHODS = %i[includes preload eager_load].freeze
+    RELATION_WRAPPERS = %i[pagy paginate page kaminari with_pagy].freeze
+    SINGLE_RECORD_METHODS = %i[find find_by find_by! first first! last last! take take! sole find_sole_by
+                               new build current_user current_account].freeze
+    RENDER_METHODS = %i[render render_as_hash render_as_json render_as_json! serialize].freeze
+    SERIALIZER_SUFFIXES = %w[Blueprint Serializer Resource].freeze
+
+    # serializer_basename => [ { view: sym_or_nil, preloaded: Set, collection: bool }, ... ]
+    attr_reader :usages
+
+    def initialize
+      @usages = Hash.new { |h, k| h[k] = [] }
+    end
+
+    def parse_file(ast)
+      return unless ast
+
+      each_scope(ast) do |body|
+        var_values = collect_assignments(body)
+        find_render_sites(body, var_values)
+      end
+    end
+
+    # Whether an association read in `view` of `serializer` can be proven safe.
+    # `view` is the Blueprinter view the field lives in (nil = a base/default
+    # field, rendered by every site). The field is safe when, at every render
+    # site that renders it, the association is eager-loaded OR the site passes a
+    # single record. To avoid hiding a genuine N+1 we never conclude "safe" when
+    # we cannot see the render sites for a named view (it may be rendered
+    # dynamically) — only an EXISTING, uniformly-safe set of sites suppresses.
+    def safe_access?(serializer, view, association)
+      sites = sites_rendering(serializer, view)
+      return false if sites.empty?
+
+      sites.all? { |s| !s[:collection] || s[:preloaded].include?(association) }
+    end
+
+    def known_serializer?(serializer)
+      @usages.key?(serializer)
+    end
+
+    private
+
+    # Sites that render a field of the given view. A base field (view nil) is
+    # rendered by every site. A named-view field is rendered by sites that
+    # explicitly request that view.
+    def sites_rendering(serializer, view)
+      sites = @usages[serializer]
+      return [] unless sites
+
+      view.nil? ? sites : sites.select { |s| s[:view] == view }
+    end
+
+    def each_scope(ast)
+      yield ast
+      collect_defs(ast).each { |d| yield(def_body(d)) }
+    end
+
+    def collect_defs(node, acc = [])
+      return acc unless node.is_a?(Parser::AST::Node)
+
+      node.children.each do |child|
+        next unless child.is_a?(Parser::AST::Node)
+
+        acc << child if %i[def defs].include?(child.type)
+        collect_defs(child, acc)
+      end
+      acc
+    end
+
+    def def_body(node)
+      node.type == :def ? node.children[2] : node.children[3]
+    end
+
+    def collect_assignments(body)
+      values = {}
+      walk(body) do |node|
+        case node.type
+        when :lvasgn, :ivasgn
+          values[node.children[0]] = node.children[1] if node.children[1]
+        when :masgn
+          collect_multi_assignment(node, values)
+        end
+      end
+      values
+    end
+
+    def collect_multi_assignment(node, values)
+      mlhs, rhs = node.children
+      return unless mlhs && rhs
+
+      mlhs.children.each do |t|
+        next unless %i[lvasgn ivasgn].include?(t&.type)
+
+        values[t.children[0]] = rhs
+      end
+    end
+
+    def find_render_sites(body, var_values)
+      walk(body) do |node|
+        next unless node.type == :send && RENDER_METHODS.include?(node.children[1])
+
+        serializer = serializer_name(node.children[0])
+        next unless serializer
+
+        arg = node.children[2]
+        view = view_option(node)
+        record_site(serializer, view, arg, var_values)
+      end
+    end
+
+    # `Foo::BarBlueprint.render_as_hash` => "BarBlueprint"; for Alba, the receiver
+    # is `BarResource.new(arg)` so peel the `.new`.
+    def serializer_name(recv)
+      return nil unless recv.is_a?(Parser::AST::Node)
+
+      const = recv.type == :send ? recv.children[0] : recv
+      return nil unless const.is_a?(Parser::AST::Node) && const.type == :const
+
+      name = const.children[1].to_s
+      SERIALIZER_SUFFIXES.any? { |s| name.end_with?(s) } ? name : nil
+    end
+
+    def view_option(node) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+      node.children[3..].each do |arg|
+        next unless arg.is_a?(Parser::AST::Node) && arg.type == :hash
+
+        arg.children.each do |pair|
+          k = pair.children[0]
+          if k&.type == :sym && k.children[0] == :view && pair.children[1]&.type == :sym
+            return pair.children[1].children[0]
+          end
+        end
+      end
+      nil
+    end
+
+    def record_site(serializer, view, arg, var_values)
+      resolved = resolve_value(arg, var_values)
+      @usages[serializer] << {
+        view: view,
+        preloaded: extract_preloads(resolved, var_values),
+        collection: !single_record?(resolved, var_values)
+      }
+    end
+
+    # Resolve a local/ivar render arg to the expression it was assigned, so
+    # `render(user_points)` after `user_points = UserPoint.includes(:point)` is
+    # seen as the relation, not an opaque variable.
+    def resolve_value(node, var_values, depth = 0)
+      return node if depth > 5 || !node.is_a?(Parser::AST::Node)
+      return node unless %i[lvar ivar].include?(node.type)
+
+      assigned = var_values[node.children[0]]
+      assigned ? resolve_value(assigned, var_values, depth + 1) : node
+    end
+
+    def extract_preloads(node, var_values, depth = 0) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+      preloads = Set.new
+      return preloads if depth > 8 || !node.is_a?(Parser::AST::Node)
+
+      current = node
+      while current.is_a?(Parser::AST::Node) && current.type == :send
+        current.children[2..].each { |a| collect_symbols(a, preloads) } if PRELOAD_METHODS.include?(current.children[1])
+        current.children[2..].each do |a|
+          if RELATION_WRAPPERS.include?(current.children[1])
+            preloads.merge(extract_preloads(resolve_value(a, var_values), var_values,
+                                            depth + 1))
+          end
+        end
+        current = current.children[0]
+      end
+      preloads
+    end
+
+    def collect_symbols(arg, set) # rubocop:disable Metrics/CyclomaticComplexity
+      case arg&.type
+      when :sym then set << arg.children[0]
+      when :array then arg.children.each { |c| collect_symbols(c, set) }
+      when :hash
+        arg.children.each do |pair|
+          key = pair.children[0]
+          set << key.children[0] if key&.type == :sym
+          collect_symbols(pair.children[1], set)
+        end
+      end
+    end
+
+    def single_record?(node, var_values, depth = 0)
+      return false if depth > 6 || !node.is_a?(Parser::AST::Node)
+
+      case node.type
+      when :send
+        method = node.children[1]
+        return true if SINGLE_RECORD_METHODS.include?(method)
+
+        single_record?(node.children[0], var_values, depth + 1)
+      when :array
+        node.children.size == 1
+      else
+        false
+      end
+    end
+
+    def walk(node, &block)
+      return unless node.is_a?(Parser::AST::Node)
+
+      yield node
+      node.children.each { |c| walk(c, &block) }
+    end
+  end
+end

data/lib/eager_eye/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module EagerEye
-  VERSION = "1.3.0"
+  VERSION = "1.3.1"
 end

data/lib/eager_eye.rb

@@ -10,6 +10,8 @@ require_relative "eager_eye/delegation_parser"
 require_relative "eager_eye/scope_parser"
 require_relative "eager_eye/validation_parser"
 require_relative "eager_eye/method_query_parser"
+require_relative "eager_eye/schema_parser"
+require_relative "eager_eye/serializer_usage_parser"
 require_relative "eager_eye/detectors/base"
 require_relative "eager_eye/detectors/loop_association"
 require_relative "eager_eye/detectors/serializer_nesting"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: eager_eye
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.3.1
 platform: ruby
 authors:
 - hamzagedikkaya
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-20 00:00:00.000000000 Z
+date: 2026-06-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ast
@@ -96,7 +96,9 @@ files:
 - lib/eager_eye/reporters/json.rb
 - lib/eager_eye/rspec.rb
 - lib/eager_eye/rspec/matchers.rb
+- lib/eager_eye/schema_parser.rb
 - lib/eager_eye/scope_parser.rb
+- lib/eager_eye/serializer_usage_parser.rb
 - lib/eager_eye/validation_parser.rb
 - lib/eager_eye/version.rb
 - sig/eager_eye.rbs