activerecord-precompiled 0.1.0

data/lib/active_record_precompiled/rewriter.rb

@@ -0,0 +1,917 @@
+# frozen_string_literal: true
+
+require "prism"
+require "digest"
+
+module ActiveRecordPrecompiled
+  # Source-to-source compiler. Finds ActiveRecord query chains rooted at a
+  # model constant, asks ActiveRecord (via Capture) for the SQL each one
+  # produces, and replaces the chain with a call to a precompiled Site while
+  # keeping the original chain as the fallback block:
+  #
+  #   User.where(name: n).first
+  #   # becomes
+  #   ::ActiveRecordPrecompiled::Sites::S1a2b3c4d5e_0.call(n) { |__xs0| User.where(name: __xs0).first }
+  #
+  # Site definitions go into a single `BEGIN { }` line at the end of the file
+  # (before `__END__`), so every existing line keeps its line number.
+  class Rewriter
+    MARKER = "# activerecord-precompiled"
+    # The generated definitions line; its presence means the file was already rewritten.
+    GENERATED_LINE = /^BEGIN \{ ::ActiveRecordPrecompiled::Site\.define\(.*\} # activerecord-precompiled v/
+
+    BUILDERS = %i[all where order group limit offset includes preload].freeze
+    TERMINATORS = {
+      to_a: :records, first: :one, take: :one, find_by: :one, last: :last,
+      first!: :one!, take!: :one!, find: :one!, find_by!: :one!,
+      count: :count, exists?: :exists, pluck: :pluck,
+      sum: :calculate, maximum: :calculate, minimum: :calculate, average: :calculate,
+    }.freeze
+    # Enumerable methods called on a relation just load it; we rewrite the
+    # relation itself and leave the method (and its block) in place.
+    ENUMERABLE = %i[each map flat_map filter_map each_with_index each_with_object index_by group_by].freeze
+
+    # Calls whose result is a collection: passing one to `where` means `IN (...)`,
+    # which the precompiled `= ?` can never serve.
+    COLLECTION_METHODS = %i[map flat_map filter_map collect compact uniq pluck ids to_a keys values select reject].freeze
+
+    Result = Data.define(:source, :sites, :skipped)
+    Skip = Class.new(StandardError)
+
+    def initialize(path:)
+      @path = path
+      @prefix = "S#{Digest::SHA256.hexdigest(path.to_s)[0, 10]}"
+    end
+
+    def rewrite(source)
+      return Result.new(source, 0, []) if source.match?(GENERATED_LINE)
+
+      parse = Prism.parse(source)
+      return Result.new(source, 0, ["#{@path}: does not parse, left untouched"]) unless parse.success?
+
+      @source = source
+      @definitions = []
+      @sites = 0 # call sites; a friendly_id find defines several Sites for one
+      @skipped = []
+      @nesting = []
+      body = rewrite_range(parse.value, 0, source.bytesize)
+      return Result.new(source, 0, @skipped) if @definitions.empty?
+
+      rewritten = append_definitions(body, parse)
+      # Last line of defence: never hand back code that would break the app on boot.
+      unless Prism.parse(rewritten).success?
+        return Result.new(source, 0, @skipped + ["#{@path}: rewritten source does not parse, left untouched"])
+      end
+
+      Result.new(rewritten, @sites, @skipped)
+    end
+
+    private
+
+    # --- traversal -----------------------------------------------------------
+
+    def rewrite_range(node, from, to)
+      edits = []
+      collect(node, edits)
+      out = +""
+      cursor = from
+      edits.sort_by(&:first).each do |start, stop, text|
+        out << @source.byteslice(cursor, start - cursor) << text
+        cursor = stop
+      end
+      out << @source.byteslice(cursor, to - cursor)
+    end
+
+    def collect(node, edits)
+      return unless node
+
+      if node.is_a?(Prism::ClassNode) || node.is_a?(Prism::ModuleNode)
+        collect(node.superclass, edits) if node.is_a?(Prism::ClassNode)
+        # Track the lexical scope so bare constants resolve the way Ruby resolves them.
+        @nesting.push(namespace_for(node))
+        collect(node.body, edits)
+        @nesting.pop
+        return
+      end
+
+      if node.is_a?(Prism::CallNode)
+        if (kind = TERMINATORS[node.name]) && (edit = try_site(node, kind, terminator: true))
+          return edits << edit
+        end
+
+        if ENUMERABLE.include?(node.name) && node.block && node.receiver.is_a?(Prism::CallNode) &&
+            !TERMINATORS.key?(node.receiver.name) && (edit = try_site(node.receiver, :records, terminator: false))
+          edits << edit
+          collect(node.arguments, edits)
+          collect(node.block, edits)
+          return
+        end
+      end
+
+      node.compact_child_nodes.each { collect(it, edits) }
+    end
+
+    # --- matching ------------------------------------------------------------
+
+    def try_site(node, kind, terminator:)
+      return if node.block # a block on the terminator changes its meaning
+
+      calls = []
+      cur = node
+      while cur.is_a?(Prism::CallNode) && cur.receiver
+        calls.unshift(cur)
+        cur = cur.receiver
+      end
+      unless cur.is_a?(Prism::ConstantReadNode) || cur.is_a?(Prism::ConstantPathNode)
+        return try_association_site(cur, calls, kind, terminator, node)
+      end
+
+      terminator = terminator ? calls.pop : nil
+      # Builders, or scopes (checked against the model in build_site).
+      return unless calls.all? { BUILDERS.include?(it.name) || !it.name.end_with?("!", "?", "=") }
+      return if (calls + [terminator]).compact.any? { it.safe_navigation? || it.block }
+
+      build_site(cur, calls, terminator, kind, node)
+    rescue Skip => e
+      @skipped << "#{@path}:#{node.location.start_line}: #{e.message}"
+      nil
+    rescue StandardError => e
+      # ActiveRecord rejected the chain at build time; leave it alone, keep building.
+      @skipped << "#{@path}:#{node.location.start_line}: #{e.class}: #{e.message.lines.first&.strip}"
+      nil
+    end
+
+    def build_site(root, calls, terminator, kind, range_node)
+      model = resolve_model(root)
+      if calls.map(&:name) == [:friendly] && terminator&.name == :find
+        return build_friendly_site(model, calls.first, terminator, range_node)
+      end
+
+      validate_terminator!(terminator)
+      args = [] # [node, ...] runtime arguments, by sentinel index
+      name = :"#{@prefix}_#{@definitions.size}"
+      # A bare Model.find answers from a cached statement, not Relation#load.
+      lazy = !(calls.empty? && terminator&.name == :find)
+      @definitions << site_definition(name, model, -> { model }, calls, terminator, kind, args, lazy: lazy)
+      @sites += 1
+      [range_node.location.start_offset, range_node.location.end_offset, call_site(name, range_node, args)]
+    end
+
+    # The Site.define for a chain run on `base.call` (the model, or an
+    # association's CollectionProxy). `args` collects the runtime arguments;
+    # `key` is the probe standing for the association owner's key.
+    def site_definition(name, model, base, calls, terminator, kind, args, lazy: true, key: nil)
+      @list_args = {} # sentinel index => type, for condition values an Array may replace
+      @collection_args = {} # sentinel index => source, for arguments that look like collections
+      @id_args = [] # sentinel indices that must be an Integer or String id at runtime
+      @base = base
+      @key_probe = key
+      steps = where_chains(calls).map { |call| [call.name, ruby_args(call, model, args)] }
+      steps << (terminator ? [terminator.name, ruby_args(terminator, model, args)] : [:to_a, []])
+
+      relation, queries = capture_chain(base.call, steps)
+      raise Skip, "expected 1 query, ActiveRecord ran #{queries.size}" unless queries.size == 1
+
+      query = queries.first
+      group = group_columns(relation, kind)
+      calc = [terminator.name.to_s, steps.last[1][0].to_s] if kind == :calculate
+      kind = :"group_#{kind}" if group
+      binds = bind_specs(model, query, args.size, key: key)
+      lists = in_lists(model, steps, query, binds)
+      @collection_args.each do |index, source|
+        raise Skip, "argument is a collection or range: #{source}" unless lists.any? { binds[it][1] == index }
+      end
+      preload = preload_values(relation, kind)
+      plans = preload && Preload.compile(model, preload)
+      "::ActiveRecordPrecompiled::Site.define(#{name.inspect}, model: #{model.name.inspect}, " \
+        "kind: #{kind.inspect}, sql: #{query.sql.inspect}, binds: #{binds.inspect}, schema: #{Site.schema_of(model).inspect}" \
+        "#{", lists: #{lists.inspect}" if lists.any?}#{", ids: #{@id_args.inspect}" if @id_args.any?}#{", group: #{group.inspect}" if group}#{", calc: #{calc.inspect}" if calc}" \
+        "#{", preload: #{preload.inspect}" if preload}#{", preload_plans: #{plans.inspect}" if plans&.any?}" \
+        "#{", lazy: false" unless lazy})"
+    end
+
+    # --- association roots ---------------------------------------------------------
+
+    OWNER_PROBES = { integer: -7_000_003, string: "__ar_precompiled_owner__" }.freeze
+
+    # `owner.posts.where(...).first`, `posts.count` (self's association):
+    # the chain after a collection association. The receiver can't be typed
+    # statically, so every model with a collection association of that name
+    # gets its own Site, and an AssocSite picks one by the owner's class.
+    def try_association_site(root, calls, kind, terminator, node)
+      # A bare `posts` is a call without a receiver: the bottom of the chain.
+      calls = [root] + calls if root.is_a?(Prism::CallNode) && root.receiver.nil?
+      terminator = terminator ? calls.pop : nil
+      at = calls.rindex { association_call?(it) } or return
+      assoc, rest = calls[at], calls[(at + 1)..]
+      return unless rest.all? { BUILDERS.include?(it.name) || !it.name.end_with?("!", "?", "=") }
+      return if (rest + [terminator]).compact.any? { it.safe_navigation? || it.block } || assoc.safe_navigation?
+
+      build_association_site(assoc, rest, terminator, kind, node)
+    end
+
+    def association_call?(call)
+      call.is_a?(Prism::CallNode) && call.arguments.nil? && call.block.nil? &&
+        !BUILDERS.include?(call.name) && !TERMINATORS.key?(call.name) && association_owners.key?(call.name)
+    end
+
+    # Association name => [[owner model, reflection], ...] for collection associations.
+    def association_owners
+      @association_owners ||= ActiveRecord::Base.descendants.each_with_object(Hash.new { |h, k| h[k] = [] }) do |model, index|
+        next if model.abstract_class? || model.name.nil? || !(Object.const_get(model.name) rescue nil).equal?(model)
+
+        model.reflect_on_all_associations.each do |reflection|
+          next unless reflection.collection?
+
+          reflection = model._reflect_on_association(reflection.name) # has_and_belongs_to_many as its through association
+          index[reflection.name] << [model, reflection]
+        end
+      end
+    end
+
+    def build_association_site(assoc, calls, terminator, kind, range_node)
+      validate_terminator!(terminator)
+      # to_a/each on the association itself loads it into the owner.
+      raise Skip, "#{assoc.name} loaded as a whole" if calls.empty? && kind == :records
+
+      candidates = association_owners[assoc.name]
+      if assoc.receiver.nil? && (owner = @nesting.last).is_a?(Class) && owner < ActiveRecord::Base
+        candidates = candidates.select { |model, _| model <= owner }
+      end
+      name = :"#{@prefix}_#{@definitions.size}"
+      owners = {}
+      definitions = []
+      reasons = []
+      arg_nodes = nil
+      candidates.each_with_index do |(owner, reflection), i|
+        model, key, probe = association_target(owner, reflection)
+        args = [assoc]
+        base = -> { owner.instantiate(key => probe).public_send(reflection.name) }
+        definitions << site_definition(:"#{name}_#{i}", model, base, calls, terminator, kind, args, key: probe)
+        raise Skip, "arguments differ between owners" if arg_nodes && arg_nodes.map(&:__id__) != args.map(&:__id__)
+
+        arg_nodes = args
+        owners[owner.name] = [:"#{name}_#{i}", key]
+      rescue Skip, StandardError => e
+        reasons << "#{owner.name}.#{reflection.name}: #{e.message.lines.first&.strip}"
+      end
+      raise Skip, "#{assoc.name}: #{reasons.uniq.first(2).join("; ")}" if owners.empty?
+
+      @definitions.concat(definitions)
+      @definitions << "::ActiveRecordPrecompiled::AssocSite.define(#{name.inspect}, association: #{assoc.name.inspect}, " \
+        "direct: #{calls.empty?}, owners: #{owners.inspect})"
+      @sites += 1
+      [range_node.location.start_offset, range_node.location.end_offset, call_site(name, range_node, arg_nodes)]
+    end
+
+    # [target model, owner key attribute, probe] for an association whose
+    # query is fixed apart from the owner's key.
+    def association_target(owner, reflection)
+      raise Skip, "disable_joins" if reflection.options[:disable_joins]
+
+      reflection.chain.each do |part|
+        raise Skip, "association scope is not static" if part.scope && !Preload.static_scope?(part)
+      end
+      key = Keys.join_foreign_key(reflection.chain.last)
+      raise Skip, "composite key" unless key.is_a?(String)
+
+      probe = OWNER_PROBES[owner.type_for_attribute(key).type] or raise Skip, "owner key type"
+      [check_model!(reflection.klass, reflection.klass.name), key, probe]
+    end
+
+    # Runs the chain on ActiveRecord with the queries captured: [relation, queries].
+    def capture_chain(base, steps)
+      relation = nil
+      model = base.is_a?(Class) ? base : base.model
+      queries = with_prepared_statements(model) do
+        Capture.queries do
+          relation = steps[0...-1].inject(base) do |rel, (name, values)|
+            next rel.where.not(*values).tap { ensure_activerecord_method!(rel, :where) } if name == :not
+
+            ensure_activerecord_method!(rel, name)
+            rel.public_send(name, *values)
+          end
+          name, values = steps.last
+          ensure_activerecord_method!(relation, name)
+          relation.public_send(name, *values)
+        end
+      end
+      [relation, queries.reject { it.sql.start_with?("PRAGMA") }]
+    end
+
+    # --- arrays ------------------------------------------------------------------
+
+    # `where(id: ids)` with an Array of two or more values is `id IN (?, ...)`
+    # (`NOT IN` for where.not); one value is the scalar SQL. For each
+    # condition argument whose `= ?` becomes exactly that, `[bind position,
+    # start, stop, not]`: the Site swaps `sql[start...stop]` for an IN list.
+    def in_lists(model, steps, query, binds)
+      @list_args.filter_map do |index, type|
+        at = binds.index { it[0] == :arg && it[1] == index }
+        at && in_list(model, steps, query, binds, index, type, at)
+      end
+    end
+
+    def in_list(model, steps, query, binds, index, type, at)
+      sql = query.sql
+      question = Site.placeholder_offset(sql, at) or return nil
+      negated = sql[question - 4, 5] == " != ?"
+      start = negated ? question - 4 : question - 3
+      return nil unless negated || sql[start, 4] == " = ?"
+
+      probe = list_probe(type) or return nil
+      expected = "#{sql[0...start]}#{negated ? " NOT IN" : " IN"} (?, ?)#{sql[(question + 1)..]}"
+      _, queries = begin
+        capture_chain(@base.call, substitute(steps, index, [probe, probe]))
+      rescue StandardError
+        return nil
+      end
+      return nil unless queries.size == 1 && queries[0].sql == expected
+
+      probe_binds = queries[0].binds
+      return nil unless probe_binds.size == binds.size + 1
+
+      others = probe_binds[0...at] + probe_binds[(at + 2)..]
+      same = others.zip(binds[0...at] + binds[(at + 1)..]).all? do |bind, spec|
+        raw = bind.value_before_type_cast
+        if spec[0] == :val
+          !raw.is_a?(Capture::Sentinel) && model.with_connection { Site.db_constant(it, bind.value_for_database) } == spec[1]
+        elsif spec[0] == :key
+          !raw.is_a?(Capture::Sentinel) && raw == @key_probe
+        else
+          raw.is_a?(Capture::Sentinel) && raw.index == spec[1]
+        end
+      end
+      same ? at : nil
+    end
+
+    # A value ActiveRecord binds as itself in an IN list of this type.
+    def list_probe(type)
+      if type.respond_to?(:mapping, true) && (label = type.send(:mapping).keys.first)
+        return label.to_s
+      end
+
+      case type.type
+      when :integer then -7_000_001
+      when :string, :text then "__ar_precompiled_probe__"
+      when :float then 1.5
+      when :decimal then BigDecimal("1.5")
+      when :date then Date.new(2000, 1, 1)
+      when :datetime then Time.utc(2000, 1, 1)
+      end
+    end
+
+    # `steps` with argument `index` replaced by `value`.
+    def substitute(value, index, replacement)
+      case value
+      when Capture::Sentinel then value.index == index ? replacement : value
+      when Array then value.map { substitute(it, index, replacement) }
+      when Hash then value.transform_values { substitute(it, index, replacement) }
+      else value
+      end
+    end
+
+    # --- friendly_id -----------------------------------------------------------
+
+    FRIENDLY_FINDERS = %w[FriendlyId::FinderMethods FriendlyId::History::FinderMethods].freeze
+
+    # `Model.friendly.find(x)`: one Site per query FriendlyId may run, tied
+    # together by a FriendlySite. Only for plain :slugged/:history setups,
+    # where those queries are fixed.
+    def build_friendly_site(model, friendly, find, range_node)
+      check_friendly!(model, friendly, find)
+      args = [find.arguments.arguments.first]
+      relation = model.friendly
+      query_field = model.friendly_id_config.query_field
+
+      slug_queries = with_prepared_statements(model) do
+        sentinel = Capture::Sentinel.for(model.type_for_attribute(query_field), 0)
+        Capture.queries { relation.send(:first_by_friendly_id, sentinel) }
+      end.reject { it.sql.start_with?("PRAGMA") }
+      by_id = with_prepared_statements(model) do
+        sentinel = Capture::Sentinel.for(model.type_for_attribute(model.primary_key), 0)
+        # What FinderMethods#find's `super` runs.
+        Capture.queries { ActiveRecord::Relation.instance_method(:find).bind_call(relation, sentinel) }
+      end.reject { it.sql.start_with?("PRAGMA") }
+      history = model.friendly_id_config.finder_methods.name == "FriendlyId::History::FinderMethods"
+      raise Skip, "friendly.find ran unexpected queries" unless by_id.size == 1 && slug_queries.size == (history ? 2 : 1)
+
+      by_slug, by_history = slug_queries
+
+      parts = { slug: [:one, by_slug.sql, bind_specs(model, by_slug, 1)],
+                id: [:one!, by_id.first.sql, bind_specs(model, by_id.first, 1)] }
+      parts[:history] = [:one, *inline_arg_to_bind(model, by_history, query_field)] if history
+
+      # Nothing is defined until every part compiled.
+      names = parts.transform_values { |(kind, sql, binds)| friendly_part(model, kind, sql, binds) }
+      name = :"#{@prefix}_#{@definitions.size}"
+      @definitions << "::ActiveRecordPrecompiled::FriendlySite.define(#{name.inspect}, " \
+        "#{names.map { |k, v| "#{k}: #{v.inspect}" }.join(", ")})"
+      @sites += 1
+      [range_node.location.start_offset, range_node.location.end_offset, call_site(name, range_node, args)]
+    end
+
+    def check_friendly!(model, friendly, find)
+      nodes = find.arguments&.arguments || []
+      unless nodes.size == 1 && !hash_node?(nodes[0]) && !nodes[0].is_a?(Prism::SplatNode) && !nodes[0].is_a?(Prism::BlockArgumentNode)
+        raise Skip, "friendly.find needs exactly one id"
+      end
+      raise Skip, "friendly takes no arguments" if friendly.arguments
+      raise Skip, "heredoc argument" if heredoc?(nodes[0])
+      unless defined?(::FriendlyId::Base) && model.method(:friendly).owner == ::FriendlyId::Base
+        raise Skip, "friendly overrides ActiveRecord's (not friendly_id's own)"
+      end
+
+      config = model.friendly_id_config
+      raise Skip, "friendly_id :scoped finds within a scope" if config.uses?(:scoped)
+      raise Skip, "friendly_id finder is #{config.finder_methods}" unless FRIENDLY_FINDERS.include?(config.finder_methods.name)
+      raise Skip, "#{model.name} has a non-integer primary key" unless model.type_for_attribute(model.primary_key).type == :integer
+
+      relation = model.friendly
+      %i[find first_by_friendly_id parse_friendly_id potential_primary_key?].each do |method|
+        owner = relation.method(method).owner.name
+        raise Skip, "#{method} is overridden (#{owner})" unless FRIENDLY_FINDERS.include?(owner)
+      end
+    end
+
+    def friendly_part(model, kind, sql, binds)
+      name = :"#{@prefix}_#{@definitions.size}"
+      @definitions << "::ActiveRecordPrecompiled::Site.define(#{name.inspect}, model: #{model.name.inspect}, " \
+        "kind: #{kind.inspect}, sql: #{sql.inspect}, binds: #{binds.inspect}, schema: #{Site.schema_of(model).inspect})"
+      name
+    end
+
+    # friendly_id's history lookup compares with an Arel node, which puts the
+    # value into the SQL as a quoted literal. Make that literal a bind again.
+    def inline_arg_to_bind(model, query, attribute)
+      quoted = model.with_connection { it.quote("__ar_precompiled_arg_0__") }
+      raise Skip, "friendly_id history query doesn't contain the slug once" unless query.sql.scan(quoted).size == 1
+
+      before = query.sql[0, query.sql.index(quoted)]
+      position = before.gsub(/'(?:[^']|'')*'|"(?:[^"]|"")*"/, "").count("?")
+      sql = query.sql.sub(quoted, "?")
+      binds = bind_specs(model, Capture::Query.new(sql, query.binds), 0)
+      [sql, binds.insert(position, [:arg, 0, attribute])]
+    end
+
+    # `where.not(hash)` is two calls; the `where` without arguments only opens
+    # the chain, so drop it and let `not` stand for both.
+    def where_chains(calls)
+      calls.each_with_index.filter_map do |call, i|
+        if call.name == :where && call.arguments.nil? && !call.block
+          following = calls[i + 1]
+          raise Skip, "where.#{following&.name} is not supported" unless following&.name == :not
+
+          next
+        end
+        raise Skip, "not without where" if call.name == :not && !(i.positive? && calls[i - 1].name == :where && calls[i - 1].arguments.nil?)
+
+        call
+      end
+    end
+
+    # What Relation#load would hand to the Preloader after loading records:
+    # preload + includes, when includes doesn't turn into a JOIN.
+    def preload_values(relation, kind)
+      return nil unless relation.is_a?(ActiveRecord::Relation)
+
+      values = relation.preload_values + relation.includes_values
+      return nil if values.empty?
+      raise Skip, "includes would eager_load (JOIN) here" if relation.eager_loading?
+      raise Skip, "pluck with includes joins the included tables" if kind == :pluck
+      return nil unless %i[records one one! last].include?(kind) # count/exists? don't load records
+
+      raise Skip, "preload list is not plain symbols/hashes" unless plain_associations?(values)
+
+      values
+    end
+
+    def plain_associations?(value)
+      case value
+      when Symbol, String then true
+      when Array then value.all? { plain_associations?(it) }
+      when Hash then value.all? { |k, v| plain_associations?(k) && plain_associations?(v) }
+      else false
+      end
+    end
+
+    # Capture needs binds to tell which `?` is which argument; with prepared
+    # statements off (query_log_tags_enabled does that) AR inlines values
+    # instead. The runtime always binds its own fixed SQL, so forcing them on
+    # for the capture is safe. Fast-path queries carry no query-log comment.
+    def with_prepared_statements(model)
+      model.with_connection do |conn|
+        previous = conn.instance_variable_get(:@prepared_statements)
+        conn.instance_variable_set(:@prepared_statements, true)
+        begin
+          yield
+        ensure
+          conn.instance_variable_set(:@prepared_statements, previous)
+        end
+      end
+    end
+
+    # Overrides that call ActiveRecord's method unchanged and only touch the
+    # records it returns; Site does the same to fast-path records.
+    PASS_THROUGH = { "ArLazyPreload::Base::ClassMethods" => %i[find_by] }.freeze
+
+    # The captured SQL is only valid for every argument if the method is
+    # ActiveRecord's own. An app or gem override (Redmine's Project.find,
+    # friendly_id's finders) may pick a different query per argument.
+    def ensure_activerecord_method!(receiver, name)
+      owner = receiver.method(name).owner
+      return if owner.name&.start_with?("ActiveRecord::")
+      return if PASS_THROUGH[owner.name]&.include?(name)
+      return if scope_method?(receiver, name)
+
+      where = owner.singleton_class? ? owner.attached_object.name : (owner.name || "an anonymous module")
+      raise Skip, "#{name} overrides ActiveRecord's (defined on #{where})"
+    end
+
+    # A method ActiveRecord generated for a recorded scope, on the model and
+    # (for relations) on the relation, and not redefined by the app since.
+    def scope_method?(receiver, name)
+      model = receiver.is_a?(Class) ? receiver : receiver.model
+      return false unless Scopes.body_for(model, name)
+
+      generated = ->(m) { m.source_location&.first.to_s.end_with?("active_record/scoping/named.rb", "active_record/relation/delegation.rb") }
+      generated.(model.method(name)) && generated.(receiver.method(name))
+    end
+
+    def resolve_model(root)
+      name = root.slice
+      model = resolve_constant(root)
+      name = model.name if model.is_a?(Module) && model.name
+      raise Skip, "#{name} is not an ActiveRecord model" unless model.is_a?(Class) && model < ActiveRecord::Base
+
+      check_model!(model, name)
+    rescue NameError
+      raise Skip, "cannot resolve #{name}"
+    end
+
+    def check_model!(model, name)
+      raise Skip, "#{name} is abstract" if model.abstract_class?
+      raise Skip, "#{name} has a default_scope" if model.default_scopes.any?
+      model.with_connection do |conn|
+        raise Skip, "#{name} is not on SQLite" unless conn.is_a?(ActiveRecord::ConnectionAdapters::SQLite3Adapter)
+      end
+      raise Skip, "#{name} has no table" unless model.table_exists?
+
+      model.load_schema
+      model
+    end
+
+    # nil when the namespace can't be resolved; lookups inside it are then skipped.
+    def namespace_for(node)
+      resolve_constant(node.constant_path)
+    rescue NameError, Skip
+      nil
+    end
+
+    # Constant lookup as Ruby does it at this point in the file: enclosing
+    # lexical scopes first, then the innermost scope's ancestors, then Object.
+    def resolve_constant(node)
+      case node
+      when Prism::ConstantReadNode
+        lexical_lookup(node.name)
+      when Prism::ConstantPathNode
+        return Object.const_get(node.name, false) unless node.parent
+
+        scope = resolve_constant(node.parent)
+        owner = scope.ancestors.find { it.const_defined?(node.name, false) && !(it == Object && scope != Object) }
+        owner ? owner.const_get(node.name, false) : raise(NameError, "uninitialized constant #{node.slice}")
+      else
+        raise Skip, "unsupported constant expression #{node.slice}"
+      end
+    end
+
+    def lexical_lookup(name)
+      raise Skip, "cannot resolve the enclosing namespace" if @nesting.include?(nil)
+
+      @nesting.reverse_each { |scope| return scope.const_get(name, false) if scope.const_defined?(name, false) }
+      ((@nesting.last&.ancestors || []) + [Object]).each do |scope|
+        return scope.const_get(name, false) if scope.const_defined?(name, false)
+      end
+      raise NameError, "uninitialized constant #{name}"
+    end
+
+    def validate_terminator!(terminator)
+      return unless terminator
+
+      count = terminator.arguments&.arguments&.size || 0
+      ok = case terminator.name
+      when :find then count == 1
+      when :find_by, :find_by! then count == 1
+      when :exists? then count <= 1
+      when :pluck then count >= 1
+      when :sum, :maximum, :minimum, :average then count == 1
+      else count.zero?
+      end
+      raise Skip, "unsupported arguments to #{terminator.name}" unless ok
+    end
+
+    # Converts call arguments to Ruby values for the build-time ActiveRecord
+    # call. Literals are passed through (and end up as constants in the SQL or
+    # binds); anything else becomes a Sentinel and a runtime argument.
+    def ruby_args(call, model, args)
+      nodes = call.arguments&.arguments || []
+      raise Skip, "block argument" if call.block
+
+      case call.name
+      when :where, :not, :find_by, :find_by!
+        raise Skip, "#{call.name} needs exactly one hash" unless nodes.size == 1 && hash_node?(nodes[0])
+
+        [conditions(nodes[0], model, args)]
+      when :exists?
+        return [] if nodes.empty?
+        return [conditions(nodes[0], model, args)] if hash_node?(nodes[0])
+
+        # exists?(id): where(primary_key => id). false, nil, an Array or a
+        # record mean something else, so only an Integer or String id takes
+        # the fast path.
+        raise Skip, "exists? with a composite primary key" unless model.primary_key.is_a?(String)
+
+        id = value_or_sentinel(nodes[0], args, model.type_for_attribute(model.primary_key))
+        @id_args << id.index if id.is_a?(Capture::Sentinel)
+        [id]
+      when :find
+        [value_or_sentinel(nodes[0], args, model.type_for_attribute(model.primary_key))]
+      when :limit, :offset
+        raise Skip, "#{call.name} needs an integer literal" unless nodes.size == 1 && nodes[0].is_a?(Prism::IntegerNode)
+
+        [nodes[0].value]
+      when :includes, :preload
+        raise Skip, "#{call.name} needs arguments" if nodes.empty?
+
+        nodes.map { literal(it) }
+      when :sum, :maximum, :minimum, :average
+        column = literal(nodes[0])
+        unless (column.is_a?(Symbol) || column.is_a?(String)) && model.columns_hash.key?(column.to_s)
+          raise Skip, "#{call.name} of non-column"
+        end
+
+        [column]
+      when :group
+        raise Skip, "group needs arguments" if nodes.empty?
+
+        nodes.map { literal(it) }.tap do |values|
+          raise Skip, "group by non-column" unless values.all? { (it.is_a?(Symbol) || it.is_a?(String)) && model.columns_hash.key?(it.to_s) }
+        end
+      when :order, :pluck
+        raise Skip, "#{call.name} needs literal arguments" if nodes.empty?
+
+        nodes.map { call.name == :order && arel_sql(it) || literal(it) }.tap do |values|
+          if call.name == :pluck && !values.all? { (it.is_a?(Symbol) || it.is_a?(String)) && model.attribute_types.key?(it.to_s) }
+            raise Skip, "pluck of non-attribute"
+          end
+        end
+      else
+        return scope_args(call, nodes, model, args) if Scopes.body_for(model, call.name)
+        raise Skip, "#{call.name} is not a scope" unless nodes.empty?
+
+        [] # not a scope: ensure_activerecord_method! explains why it is skipped
+      end
+    end
+
+    # --- scopes --------------------------------------------------------------
+
+    def scope_args(call, nodes, model, args)
+      begin
+        analysis = (@scope_analyzer ||= ScopeAnalyzer.new).analyze(model, call.name)
+      rescue ScopeAnalyzer::NotStatic => e
+        raise Skip, "#{call.name} is not a static scope: #{e.message}"
+      end
+      if nodes.size != analysis.arity || nodes.any? { hash_node?(it) || it.is_a?(Prism::SplatNode) || it.is_a?(Prism::BlockArgumentNode) }
+        raise Skip, "unsupported arguments to scope #{call.name}"
+      end
+
+      nodes.each_with_index.map do |node, i|
+        column = analysis.param_columns[i]
+        next value_or_sentinel(node, args, ActiveModel::Type::Value.new) unless column
+
+        value_or_sentinel(node, args, *condition_type(model, column), list: true)
+      end
+    end
+
+    # `Arel.sql("COUNT(*) DESC")` with a plain string: fixed SQL, like a literal.
+    def arel_sql(node)
+      return nil unless node.is_a?(Prism::CallNode) && node.name == :sql && node.arguments&.arguments&.size == 1 && !node.block
+      return nil unless %w[Arel ::Arel].include?(node.receiver&.slice) && node.arguments.arguments[0].is_a?(Prism::StringNode)
+
+      Arel.sql(node.arguments.arguments[0].unescaped)
+    end
+
+    # The group columns of a grouped `count`/`sum`/..., which returns a Hash keyed by them.
+    def group_columns(relation, kind)
+      return nil unless relation.respond_to?(:group_values) && relation.group_values.any?
+      return nil unless %i[count calculate].include?(kind)
+
+      relation.group_values.map(&:to_s)
+    end
+
+    def hash_node?(node) = node.is_a?(Prism::KeywordHashNode) || node.is_a?(Prism::HashNode)
+
+    def conditions(hash, model, args)
+      hash.elements.to_h do |assoc|
+        raise Skip, "splat in conditions" unless assoc.is_a?(Prism::AssocNode)
+        raise Skip, "non-literal key" unless assoc.key.is_a?(Prism::SymbolNode) || assoc.key.is_a?(Prism::StringNode)
+
+        key = assoc.key.unescaped
+        [key.to_sym, value_or_sentinel(assoc.value, args, *condition_type(model, key), list: true)]
+      end
+    end
+
+    # The type a `where(key: v)` value is cast with and, for a belongs_to key,
+    # the primary key read off a record value.
+    def condition_type(model, key)
+      return [model.type_for_attribute(key), nil] if model.columns_hash.key?(key)
+
+      reflection = ScopeAnalyzer.belongs_to_key(model, key)
+      raise Skip, reflection.delete("`") if reflection.is_a?(String)
+
+      [model.type_for_attribute(reflection.foreign_key.to_s), Keys.join_primary_key(reflection).to_s]
+    end
+
+    # `list: true` for a condition value, which may also be an Array at runtime
+    # (see #in_lists); other collections can't be compiled.
+    def value_or_sentinel(node, args, type, record_key = nil, list: false)
+      literal(node)
+    rescue Skip
+      list &&= record_key.nil? && !Site.encrypted?(type)
+      if collection?(node)
+        raise Skip, "argument is a collection or range: #{node.slice}" unless list && !range?(node)
+
+        @collection_args[args.size] = node.slice
+      end
+      raise Skip, "heredoc argument" if heredoc?(node)
+
+      @list_args[args.size] = type if list
+      args << node
+      Capture::Sentinel.for(type, args.size - 1, record_key:)
+    end
+
+    def range?(node)
+      node = node.body.body.first while node.is_a?(Prism::ParenthesesNode) && node.body.is_a?(Prism::StatementsNode) && node.body.body.size == 1
+      node.is_a?(Prism::RangeNode)
+    end
+
+    def heredoc?(node)
+      return true if node.respond_to?(:opening_loc) && node.opening_loc&.slice&.start_with?("<<")
+
+      node.compact_child_nodes.any? { heredoc?(it) }
+    end
+
+    def collection?(node)
+      while node.is_a?(Prism::ParenthesesNode) && node.body.is_a?(Prism::StatementsNode) && node.body.body.size == 1
+        node = node.body.body.first
+      end
+      case node
+      when Prism::RangeNode, Prism::ArrayNode then true
+      when Prism::CallNode then COLLECTION_METHODS.include?(node.name)
+      else false
+      end
+    end
+
+    def literal(node)
+      case node
+      when Prism::SymbolNode then node.unescaped.to_sym
+      when Prism::StringNode then node.unescaped
+      when Prism::IntegerNode, Prism::FloatNode then node.value
+      when Prism::NilNode then nil
+      when Prism::TrueNode then true
+      when Prism::FalseNode then false
+      when Prism::ArrayNode then node.elements.map { literal(it) }
+      when Prism::HashNode, Prism::KeywordHashNode
+        node.elements.to_h do |assoc|
+          raise Skip, "splat" unless assoc.is_a?(Prism::AssocNode)
+
+          [literal(assoc.key), literal(assoc.value)]
+        end
+      else raise Skip, "not a literal: #{node&.slice}"
+      end
+    end
+
+    def bind_specs(model, query, arg_count, key: nil)
+      raise Skip, "argument leaked into SQL" if query.sql.include?("__ar_precompiled_arg_")
+
+      seen = []
+      specs = []
+      binds = query.binds
+      i = 0
+      while i < binds.size
+        bind = binds[i]
+        raw = bind.value_before_type_cast
+        if !key.nil? && !raw.is_a?(Capture::Sentinel) && raw == key
+          # The association owner's key, as AssociationScope binds it.
+          raise Skip, "owner key bound twice" if seen.include?(0)
+          raise Skip, "owner key is converted" unless bind.value_for_database == key
+
+          seen << 0
+          specs << [:key, 0, bind.name]
+        elsif raw.is_a?(Capture::Sentinel)
+          raise Skip, "argument bound twice" if seen.include?(raw.index)
+          raise Skip, "unexpected bind type for #{bind.name}" unless bind.type.equal?(model.type_for_attribute(bind.name))
+
+          seen << raw.index
+          specs << if Site.encrypted?(bind.type)
+            encrypted_spec(model, bind, raw.index, 1)
+          elsif raw.record_key
+            [:arg, raw.index, bind.name, raw.record_key]
+          else
+            [:arg, raw.index, bind.name]
+          end
+        elsif (expanded = extended_encrypted_bind(model, binds, i, arg_count, seen))
+          index, size = expanded
+          seen << index
+          specs << encrypted_spec(model, bind, index, size)
+          i += size
+          next
+        else
+          # The ciphertext would be made with the build's keys.
+          raise Skip, "constant compared to encrypted attribute #{bind.name}" if Site.encrypted?(model.type_for_attribute(bind.name))
+
+          value = model.with_connection { Site.db_constant(it, bind.value_for_database) }
+          raise Skip, "non-literal constant bind" if value.equal?(Site::FALLBACK)
+
+          specs << [:val, value, bind.name]
+        end
+        i += 1
+      end
+      raise Skip, "argument not bound" unless seen.sort == (0...arg_count).to_a
+
+      specs
+    end
+
+    # `[:enc, index, attribute, size, state]`: a deterministic encrypted
+    # attribute, bound as `size` values (the ciphertext, plus what
+    # extend_queries adds). `state` is the encryption setup the SQL assumes.
+    def encrypted_spec(model, bind, index, size)
+      type = model.type_for_attribute(bind.name)
+      raise Skip, "non-deterministic encrypted attribute #{bind.name}" unless type.deterministic?
+
+      [:enc, index, bind.name, size, Site.encryption_state(type)]
+    end
+
+    # With extend_queries, `where(email: x)` becomes `email IN (?, ?)`, bound
+    # to x already serialized by the attribute type and its previous types
+    # (e.g. the clear text). Which argument, and how many binds, if so.
+    def extended_encrypted_bind(model, binds, at, arg_count, seen)
+      type = model.type_for_attribute(binds[at].name)
+      return nil unless Site.encrypted?(type) && type.deterministic? && !type.previous_types.empty?
+
+      (0...arg_count).each do |index|
+        next if seen.include?(index)
+
+        sentinel = Capture::Sentinel.new(index)
+        forms = [type, *type.previous_types].map { it.serialize(sentinel) }
+        window = binds[at, forms.size]
+        next unless window.size == forms.size && window.all? { it.name == binds[at].name }
+        return [index, forms.size] if window.map(&:value_for_database) == forms
+      end
+      nil
+    end
+
+    # --- code generation -----------------------------------------------------
+
+    def call_site(name, range_node, args)
+      raise Skip, "heredoc in query chain" if heredoc?(range_node)
+
+      params = args.each_index.map { "__xs#{it}" }
+      fallback = +""
+      cursor = range_node.location.start_offset
+      args.each_with_index do |arg, i|
+        # `where(name:)` is shorthand for `where(name: name)`; spell it out in the fallback.
+        replacement = arg.is_a?(Prism::ImplicitNode) ? "#{arg.value.name}: #{params[i]}" : params[i]
+        fallback << @source.byteslice(cursor, arg.location.start_offset - cursor) << replacement
+        cursor = arg.location.end_offset
+      end
+      fallback << @source.byteslice(cursor, range_node.location.end_offset - cursor)
+
+      call_args = args.map do |arg|
+        next arg.value.name.to_s if arg.is_a?(Prism::ImplicitNode)
+
+        rewrite_range(arg, arg.location.start_offset, arg.location.end_offset)
+      end
+      call = "::ActiveRecordPrecompiled::Sites::#{name}.call"
+      call << "(#{call_args.join(", ")})" unless args.empty?
+      block_params = params.empty? ? "" : " |#{params.join(", ")}|"
+      # Newlines in the arguments plus newlines left in the fallback add up to
+      # the original count, so following lines keep their numbers.
+      "#{call} {#{block_params} #{fallback} }"
+    end
+
+    def append_definitions(body, parse)
+      line = "BEGIN { #{@definitions.join("; ")} } #{MARKER} v#{VERSION}\n"
+      if (data = parse.data_loc)
+        offset = data.start_offset
+        head = body.byteslice(0, body.bytesize - (@source.bytesize - offset))
+        tail = body.byteslice(head.bytesize, body.bytesize)
+        head << "\n" unless head.end_with?("\n")
+        head + line + tail
+      else
+        body << "\n" unless body.end_with?("\n")
+        body + line
+      end
+    end
+  end
+end