graphql-constant_queries 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b6f017ef6ae0861d8033ecef935e85850e657f058384fbfc68d1ef210826f3b7
+  data.tar.gz: f638d4244ce7907e2952c03599a635bc48fd9de0b546957913e9c7f6ee99377d
+SHA512:
+  metadata.gz: dc6ab17bb9a9d962f009f656ed5edd5f7737af95bd2fc3c377444eed783e53b9376fe521894becef5eec827391b688ecd6ab436512faac3e60dc379dab97b419
+  data.tar.gz: 248b26f6e0b2bff569145bd7ed0fd585284a8454e97b6340931e8527dc1287a650fa82dc78aeb5f4b2eaa3fd643a82fdc3ca4fe3d7aa6b32882ead44a9422bcd

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stephen Crosby
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,138 @@
+# graphql-constant_queries
+
+Prove, in tests, that every field of every graphql-ruby object type issues the
+same number of ActiveRecord SQL statements whether it resolves across 2
+objects or 3. A field whose count grows with the object count has an N+1, and
+it fails in the spec of the type that causes it.
+
+## Setup
+
+```ruby
+# Gemfile
+gem "graphql-constant_queries", group: :test
+```
+
+Configure it after the app boots but before spec files load, e.g. in
+`spec/support/constant_queries.rb` required from `rails_helper.rb` (or wherever
+the app is loaded):
+
+```ruby
+require "graphql/constant_queries/rspec"
+
+GraphQL::ConstantQueries.configure do |c|
+  c.source_root = Rails.root                   # default: Dir.pwd
+  c.context = -> { {current_user: user} }      # evaluated in each example; default: {}
+  c.schema MySchema, exceptions_path: "spec/graphql/my_schema_constant_queries.yml"
+end
+```
+
+Per-schema options (`exceptions_path`, `context`, `spec_pattern`) override the
+globals. A type reachable from several schemas belongs to the first registered.
+
+## The three checks
+
+- **A. Every type has a spec.** In the schema's spec:
+
+  ```ruby
+  RSpec.describe MySchema do
+    has_specs_for_all_types except: /Error\z/
+  end
+  ```
+
+  `except:` (a Regexp or an array of them, matched against type names) only
+  relaxes this check: an excluded type that has a spec still gets B.
+
+- **B. Every type spec declares `has_constant_queries`.** The spec at a type's
+  conventional path gets a `declares has_constant_queries` example that fails
+  until it does.
+
+- **C. Every field is checked.** `has_constant_queries` generates a check per
+  field:
+
+  ```ruby
+  RSpec.describe Types::Document do
+    has_constant_queries do
+      let(:user) { create(:user, :admin) }                  # context for every check
+      default_objects { |n| create_list(:document, n, user: user) }  # required
+
+      resolving :deleted_by_user do                          # customize a field's check
+        objects { |n| create_list(:document, n, :deleted, user: user) }
+      end
+      resolving :page_data, page: 1                          # add a check with arguments
+      resolving :page_data, page: -> { create(:page).number }  # evaluated in the example
+      resolving :owner_permissions do
+        let!(:owner) { create(:user) }                       # applies to this check only
+        objects { |n| create_list(:document, n, user: owner) }
+      end
+    end
+  end
+  ```
+
+  Keywords are the field's Ruby argument names. A `resolving` block gets its
+  own example, so its lets apply only to that check and `rspec file:LINE`
+  reruns it. Every other check shares one example, `resolving with default
+  objects`, which fails with every problem it found.
+
+## Spec paths
+
+`spec_pattern` defaults to `spec/%{source}_spec.rb`, where `%{source}` is the
+type's file relative to `source_root/app` without `.rb`
+(`app/graphql/types/foo.rb` → `spec/graphql/types/foo_spec.rb`). A type
+defined in a file named for something else, like a generated wrapper, gets the
+path autoloading expects: its underscored name under the same top-level
+directory. `%{name}` is the underscored class name. `spec_pattern` may also be
+a callable `->(type) { path }`.
+
+## Writing good checks
+
+- **Single objects need data.** A field returning one object must be non-null
+  on every object, because a nil foreign key skips the load and proves
+  nothing.
+- **Vary the records resolvers walk.** Repeated loads of one record hit the
+  query cache, so objects sharing a parent hide per-object loads. Give each
+  object its own parent.
+- **Lists and connections may be empty.** Their load still runs per object.
+  Connections select `nodes { __typename }` plus argument-free counters like
+  `totalCount`.
+- **Hidden objects fail.** A null object means the authorizer hid it and the
+  field never resolved.
+- **Hidden fields aren't checked.** A field not visible in the check's context
+  is left out; an example with no visible fields is skipped.
+- **Empty builds prove nothing.** Make sure `default_objects` returns `n`
+  objects.
+- **Single objects are checked one level deep.** A single-object field selects
+  only `__typename`, so the returned object's authorizer runs but its fields
+  don't.
+- Runs happen under the ActiveRecord query cache, as in a real request. Each
+  run reloads its objects and the records in context, and each check runs in a
+  savepoint, so nothing one run loads or writes carries into the next. Objects
+  that aren't persisted records are rebuilt for each check.
+
+## Exceptions file
+
+A flat YAML list of `Type.field` keys whose checks don't pass yet:
+
+```yaml
+- Types::Document.pageData
+```
+
+A key covers every check of the field. Once all of them pass, the type's group
+fails until you remove the key. Runs filtered to some of a field's checks never
+report it. Every key must name a real field of a type in that schema, or the
+file fails to load. The list only shrinks; don't add keys for new code.
+
+## What it proves
+
+Objects reach the type through a test-only subclass of the real schema whose
+only root field is `objects: [Type]`, so every type is checked as a list even
+if clients only reach it one at a time. That proves each field batches across
+several objects, which also covers aliased siblings. It doesn't cover:
+
+- root fields (query, mutation, subscription), generated mutation payloads,
+  connections, and edges;
+- behavior that depends on what an ancestor field preloaded or put in context,
+  except as far as a spec's lets set the same context.
+
+## License
+
+MIT.

data/lib/graphql/constant_queries/check.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module ConstantQueries
+    # One field resolved with one set of arguments. +keywords+ are as written
+    # in the spec; +arguments+ are the same values keyed by GraphQL argument
+    # name. A Proc value is evaluated per run, for values that need records.
+    Check = Data.define(:type, :field, :keywords, :arguments) do
+      def self.build(type, name, keywords = {})
+        field = type.fields.each_value.find { |f| f.original_name == name.to_sym || f.graphql_name == name.to_s }
+        raise ArgumentError, "#{label(type)} has no field #{name}" unless field
+
+        arguments = keywords.to_h do |keyword, value|
+          argument = field.all_argument_definitions.find { |arg| arg.keyword == keyword }
+          raise ArgumentError, "#{label(type)}.#{field.original_name} has no argument #{keyword}" unless argument
+
+          [argument.graphql_name, value]
+        end
+        new(type: type, field: field, keywords: keywords, arguments: arguments)
+      end
+
+      def self.label(type)
+        type.name || type.graphql_name
+      end
+
+      # [type name, field name] from an exceptions key like "Types::Foo.barBaz", or nil.
+      def self.split_key(key)
+        match = /\A(?<type>[A-Z][\w:]*)\.(?<field>\w+)\z/.match(key.to_s) or return
+        [match[:type], match[:field]]
+      end
+
+      # The exceptions key, shared by every check of the field.
+      def key
+        "#{self.class.label(type)}.#{field.graphql_name}"
+      end
+
+      def description
+        "resolving #{field.original_name}#{qualifier}"
+      end
+
+      def qualifier
+        return "" if keywords.empty?
+
+        " with #{keywords.map { |keyword, value| "#{keyword}: #{value.is_a?(Proc) ? "(computed)" : value.inspect}" }.join(", ")}"
+      end
+
+      # +arguments+ with each Proc value replaced by +evaluator+.call(value).
+      def arguments_with(evaluator)
+        arguments.transform_values { |value| value.is_a?(Proc) ? evaluator.call(value) : value }
+      end
+
+      def requires_arguments?
+        field.all_argument_definitions.any? { |arg| arg.type.non_null? && !arg.default_value? }
+      end
+    end
+  end
+end

data/lib/graphql/constant_queries/configuration.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module ConstantQueries
+    class Configuration
+      DEFAULT_SPEC_PATTERN = "spec/%{source}_spec.rb"
+
+      # One schema's settings, with the globals filled in where it set none.
+      SchemaConfig = Data.define(:schema, :exceptions_path, :context, :spec_pattern)
+
+      attr_accessor :spec_pattern, :context, :docs_url
+      attr_reader :source_root
+
+      def initialize
+        self.source_root = Dir.pwd
+        @spec_pattern = DEFAULT_SPEC_PATTERN
+        @context = -> { {} }
+        @docs_url = README_URL
+        @schemas = {}
+      end
+
+      def source_root=(path)
+        @source_root = Pathname(path).expand_path
+      end
+
+      # Registers +schema+; options override the globals for its types.
+      # +exceptions_path+ is relative to source_root.
+      def schema(schema, exceptions_path: nil, context: nil, spec_pattern: nil)
+        unless schema.is_a?(Class) && schema < GraphQL::Schema
+          raise ArgumentError, "#{schema.inspect} isn't a GraphQL::Schema subclass"
+        end
+        raise ArgumentError, "#{schema} is already registered" if @schemas.key?(schema)
+
+        @schemas[schema] = {exceptions_path:, context:, spec_pattern:}
+      end
+
+      def registered?(klass)
+        @schemas.key?(klass)
+      end
+
+      # Registered schemas' settings, in registration order.
+      def schemas
+        @schemas.keys.map { |schema| for_schema(schema) }
+      end
+
+      # Settings for +schema+; just the globals when it isn't registered.
+      def for_schema(schema)
+        options = @schemas.fetch(schema, {})
+        path = options[:exceptions_path]
+        SchemaConfig.new(
+          schema: schema,
+          exceptions_path: path && source_root.join(path),
+          context: options[:context] || context,
+          spec_pattern: options[:spec_pattern] || spec_pattern
+        )
+      end
+    end
+  end
+end

data/lib/graphql/constant_queries/exceptions.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module ConstantQueries
+    # One schema's known failures: Type.field keys whose checks don't pass
+    # yet. Keys only ever get removed.
+    class Exceptions
+      attr_reader :path
+
+      # +schema+'s exceptions, loaded once from its exceptions_path.
+      def self.for(schema)
+        @cache ||= {}
+        cached = @cache[schema]
+        raise cached if cached.is_a?(ConfigurationError)
+        return cached if cached
+
+        path = GraphQL::ConstantQueries.config.for_schema(schema).exceptions_path
+        @cache[schema] = path ? load(path, Inventory.entries_for(schema)) : new
+      rescue ConfigurationError => e
+        @cache[schema] = e
+        raise
+      end
+
+      def self.reset!
+        @cache = nil
+      end
+
+      # Raises ConfigurationError unless every key names a field of one of +entries+' types.
+      def self.load(path, entries)
+        raise ConfigurationError, "#{path} doesn't exist" unless path.exist?
+
+        keys = YAML.safe_load_file(path) || []
+        raise ConfigurationError, "#{path} must be a list of Type.field keys" unless keys.is_a?(Array)
+
+        fields = entries.to_h { |entry| [entry.type.name, entry.type.fields] }
+        unknown = keys.reject do |key|
+          type, field = Check.split_key(key)
+          fields[type]&.key?(field)
+        end
+        if unknown.any?
+          raise ConfigurationError, "#{path} has keys that name no field of its schema's types:\n" \
+            "#{unknown.map { |key| "  - #{key}" }.join("\n")}"
+        end
+        new(keys, path: path)
+      end
+
+      def initialize(keys = [], path: nil)
+        @keys = Set.new(keys)
+        @path = path
+      end
+
+      def include?(key)
+        @keys.include?(key)
+      end
+
+      # The path as failure messages show it.
+      def display_path
+        return "the exceptions file" unless path
+
+        path.relative_path_from(GraphQL::ConstantQueries.config.source_root)
+      end
+    end
+  end
+end

data/lib/graphql/constant_queries/harness.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module ConstantQueries
+    # Resolves one field across 2 and 3 objects and reports why its SQL
+    # statement count depends on the number of objects, if it does.
+    class Harness
+      def initialize(schema:, type:, context:)
+        @schema = TestSchema.for(schema, type)
+        @context = context.except(:dataloader)
+        types = GraphQL::Query.new(@schema, "{ __typename }", context: @context).types
+        @builder = OperationBuilder.new(types: types, type: type)
+      end
+
+      # The field as visible in this context, or nil.
+      def visible_field(graphql_name)
+        @builder.fields.find { |field| field.graphql_name == graphql_name }
+      end
+
+      # +arguments+ maps GraphQL argument names to values; +objects_by_n+ is
+      # {1 => objects, 2 => objects, 3 => objects}. The 1-object run warms
+      # process-level caches, so state memoized on objects Reloader can't
+      # refresh is cold in both measured runs. Returns nil when the counts match.
+      def problem(field, arguments, objects_by_n)
+        operation = @builder.build(field, arguments)
+        problem = nil
+        # A savepoint keeps a failed statement or a resolver's writes from
+        # leaking into the next check.
+        ActiveRecord::Base.transaction(requires_new: true) do
+          ActiveRecord::Base.clear_query_caches_for_current_thread
+          execute(operation, Reloader.call(objects_by_n.fetch(1)), Reloader.context(@context))
+          runs = objects_by_n.slice(2, 3).transform_values { |objects| measure(operation, objects) }
+          problem = compare(field, *runs.values_at(2, 3))
+          raise ActiveRecord::Rollback
+        end
+        problem
+      rescue MissingArgument => e
+        e.message
+      rescue => e
+        "raised #{e.class}: #{e.message}"
+      end
+
+      private def measure(operation, objects)
+        reloaded = Reloader.call(objects)
+        context = Reloader.context(@context)
+        log = StatementLog.new
+        ActiveRecord::Base.clear_query_caches_for_current_thread
+        result = ActiveRecord::Base.cache { log.record { execute(operation, reloaded, context) } }
+        [result.to_h, log]
+      end
+
+      private def execute(operation, objects, context)
+        @schema.execute(
+          operation.document,
+          variables: operation.variables,
+          context: context.merge(TestSchema::OBJECTS_KEY => objects)
+        )
+      end
+
+      private def compare(field, (result2, log2), (result3, log3))
+        errors = [result2, result3].flat_map { |result| result.fetch("errors", []) }
+        return "returned GraphQL errors: #{errors.pluck("message").uniq.join("; ")}" if errors.any?
+
+        rows = [result2, result3].flat_map { |result| result.dig("data", "objects") }
+        if rows.include?(nil)
+          return "hid #{rows.count(nil)} of #{rows.size} objects; build objects visible in this context"
+        end
+        return StatementLog.growth_report(log2, log3) if log2.count != log3.count
+        return unless single_object?(field)
+
+        # A null usually means no load ran, so nothing was proven.
+        nulls = rows.count { |row| row[field.graphql_name].nil? }
+        return if nulls.zero?
+
+        "returned null for #{nulls} of #{rows.size} objects; build objects where every one has " \
+          "#{field.graphql_name}, e.g. resolving :#{field.original_name} do objects { |n| ... } end"
+      end
+
+      private def single_object?(field)
+        !OperationBuilder.leaf?(field.type) && !field.type.list? && !field.connection?
+      end
+    end
+  end
+end

data/lib/graphql/constant_queries/inventory.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module ConstantQueries
+    # Every object type in the registered schemas that must prove it issues
+    # constant queries, and the conventional spec path for each.
+    module Inventory
+      Entry = Data.define(:type, :schema, :spec_path)
+
+      # A type reachable from several schemas belongs to the first registered.
+      def self.entries
+        @entries ||= begin
+          seen = Set.new
+          GraphQL::ConstantQueries.config.schemas.flat_map do |schema_config|
+            types(schema_config.schema).filter_map do |type|
+              next unless seen.add?(type)
+
+              Entry.new(type: type, schema: schema_config.schema, spec_path: spec_path(type, schema_config.spec_pattern))
+            end
+          end
+        end
+      end
+
+      def self.entries_for(schema)
+        entries.select { |entry| entry.schema == schema }
+      end
+
+      def self.entry_for(klass)
+        @entries_by_type ||= entries.index_by(&:type)
+        @entries_by_type[klass]
+      end
+
+      def self.reset!
+        @entries = nil
+        @entries_by_type = nil
+      end
+
+      # Check A: "Type: path" for each of +schema+'s types with no spec file,
+      # skipping types whose name matches a Regexp in +except+.
+      def self.missing_specs(schema, except: [])
+        patterns = Array(except)
+        root = GraphQL::ConstantQueries.config.source_root
+        entries_for(schema).filter_map do |entry|
+          next if entry.spec_path.exist? || patterns.any? { |pattern| pattern.match?(entry.type.name) }
+
+          "#{entry.type.name}: #{entry.spec_path.relative_path_from(root)}"
+        end
+      end
+
+      def self.spec_path(type, pattern)
+        relative = if pattern.respond_to?(:call)
+          pattern.call(type)
+        else
+          format(pattern, source: source(type), name: type.name.underscore)
+        end
+        GraphQL::ConstantQueries.config.source_root.join(relative.to_s)
+      end
+
+      # The type's file relative to source_root/app, without .rb. A type
+      # defined in a file named for something else gets the path autoloading
+      # expects: its underscored name under the same top-level directory.
+      def self.source(type)
+        file = Pathname(Object.const_source_location(type.name).first)
+        relative = file.relative_path_from(app_root).sub_ext("")
+        return relative.to_s if relative.basename.to_s == type.name.demodulize.underscore
+
+        "#{relative.each_filename.first}/#{type.name.underscore}"
+      end
+
+      # Object types, excluding introspection, roots, connection and edge
+      # plumbing, and types not defined under source_root/app.
+      def self.types(schema)
+        roots = [schema.query, schema.mutation, schema.subscription].compact
+        schema.types.values.select do |type|
+          type.kind.object? && !type.introspection? && !roots.include?(type) && app_defined?(type) &&
+            !type.include?(GraphQL::Types::Relay::ConnectionBehaviors) &&
+            !type.include?(GraphQL::Types::Relay::EdgeBehaviors)
+        end
+      end
+
+      def self.app_defined?(klass)
+        klass.name.present? &&
+          Object.const_source_location(klass.name)&.first.to_s.start_with?("#{app_root}/")
+      end
+
+      def self.app_root
+        GraphQL::ConstantQueries.config.source_root.join("app")
+      end
+    end
+  end
+end

data/lib/graphql/constant_queries/ledger.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module ConstantQueries
+    # Each check's outcome for one type. Reports problems the exceptions don't
+    # cover, and exceptions whose every check ran and passed.
+    class Ledger
+      def initialize(exceptions)
+        @exceptions = exceptions
+        @problems = {}
+      end
+
+      # +problem+ is the harness's message, or nil when the check passed.
+      # Returns the failure message when the problem isn't excepted.
+      def record(check, problem)
+        @problems[check] = problem
+        return if problem.nil? || @exceptions.include?(check.key)
+
+        "#{check.key}#{check.qualifier} #{problem}"
+      end
+
+      # Exceptions among +checks+' keys that every check proved wrong. A key
+      # with any check that didn't run, e.g. under a filtered run, is never stale.
+      def stale(checks)
+        checks.group_by(&:key).filter_map do |key, key_checks|
+          key if @exceptions.include?(key) && key_checks.all? { |check| @problems.key?(check) && @problems[check].nil? }
+        end.sort
+      end
+
+      # Failure text naming the stale exceptions among +checks+, or nil.
+      def stale_report(checks)
+        keys = stale(checks)
+        return if keys.empty?
+
+        "Now passing; remove from #{@exceptions.display_path}:\n#{keys.map { |key| "  - #{key}" }.join("\n")}"
+      end
+    end
+  end
+end

data/lib/graphql/constant_queries/operation_builder.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module ConstantQueries
+    Operation = Data.define(:document, :variables)
+    MissingArgument = Class.new(StandardError)
+
+    # Builds the operation selecting one field on every object. +types+ is a
+    # visibility profile, so hidden fields are skipped.
+    class OperationBuilder
+      CONNECTION_PLUMBING = %w[edges nodes pageInfo].freeze
+
+      def self.leaf?(type)
+        kind = type.unwrap.kind
+        kind.scalar? || kind.enum?
+      end
+
+      def initialize(types:, type:)
+        @types = types
+        @type = type
+      end
+
+      def fields
+        @types.fields(@type)
+      end
+
+      # +values+ maps GraphQL argument names to values.
+      def build(field, values = {})
+        arguments = arguments_for(field, values)
+        declarations = arguments.map { |arg, variable| "$#{variable}: #{arg.type.to_type_signature}" }
+        call = arguments.map { |arg, variable| "#{arg.graphql_name}: $#{variable}" }
+        Operation.new(
+          document: "query ConstantQueries#{wrap(declarations)} { objects { __typename " \
+            "#{field.graphql_name}#{wrap(call)}#{selection(field)} } }",
+          variables: arguments.to_h { |arg, variable| [variable, values.fetch(arg.graphql_name)] }
+        )
+      end
+
+      # Arguments to pass, paired with their variable names.
+      private def arguments_for(field, values)
+        @types.arguments(field).filter_map do |arg|
+          next [arg, "#{field.graphql_name}_#{arg.graphql_name}"] if values.key?(arg.graphql_name)
+          next unless arg.type.non_null? && !arg.default_value?
+
+          raise MissingArgument, "requires argument #{arg.graphql_name}; add resolving :#{field.original_name}, #{arg.keyword}: ..."
+        end
+      end
+
+      # Select items (nodes or edges) and counters from a connection.
+      private def selection(field)
+        return "" if self.class.leaf?(field.type)
+        return " { __typename }" unless field.connection?
+
+        connection_fields = @types.fields(field.type.unwrap)
+        counters = connection_fields.select do |f|
+          !CONNECTION_PLUMBING.include?(f.graphql_name) && self.class.leaf?(f.type) &&
+            @types.arguments(f).none? { |arg| arg.type.non_null? }
+        end
+
+        nodes = connection_fields.find { |f| f.graphql_name == "nodes" }
+        if nodes
+          items_selection = self.class.leaf?(nodes.type) ? "nodes" : "nodes { __typename }"
+        else
+          edges = connection_fields.find { |f| f.graphql_name == "edges" }
+          if edges
+            node = @types.fields(edges.type.unwrap).find { |f| f.graphql_name == "node" }
+            items_selection = self.class.leaf?(node.type) ? "edges { node }" : "edges { node { __typename } }"
+          end
+        end
+
+        parts = [items_selection, *counters.map(&:graphql_name)].compact
+        return " { __typename }" if parts.empty?
+        " { #{parts.join(" ")} }"
+      end
+
+      private def wrap(parts)
+        parts.empty? ? "" : "(#{parts.join(", ")})"
+      end
+    end
+  end
+end

data/lib/graphql/constant_queries/plan.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module ConstantQueries
+    # What one type declared: its checks and how to build objects for them.
+    # +builders+ maps a check to the block building its objects; every other
+    # check uses +default_builder+. Builders take n and return n objects.
+    Plan = Data.define(:type, :schema, :checks, :default_builder, :builders) do
+      def builder_for(check)
+        builders.fetch(check, default_builder)
+      end
+    end
+  end
+end

data/lib/graphql/constant_queries/reloader.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module ConstantQueries
+    # Fresh copies of persisted records, so associations loaded while building
+    # objects or by an earlier run can't hide per-object statements. Rows
+    # without an id, like grouped selects, pass through as they are.
+    module Reloader
+      def self.call(objects)
+        objects.map { |object| reload(object) }
+      end
+
+      # Context with its records refreshed, as a new request would load them.
+      def self.context(context)
+        context.transform_values { |value| reload(value) }
+      end
+
+      def self.reload(object)
+        reloadable?(object) ? object.class.unscoped.find(object.id) : object
+      end
+
+      def self.reloadable?(object)
+        object.is_a?(ActiveRecord::Base) && object.persisted? && !object.id.nil?
+      end
+    end
+  end
+end

data/lib/graphql/constant_queries/result.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module ConstantQueries
+    # +problems+ maps each check that ran to its problem, or nil when it
+    # passed; +failures+ are the problems not excepted, as messages; +hidden+
+    # are the checks whose field isn't visible in the context.
+    Result = Data.define(:problems, :failures, :hidden) do
+      def passed?
+        failures.empty?
+      end
+    end
+  end
+end

data/lib/graphql/constant_queries/rspec/declaration.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module ConstantQueries
+    module RSpec
+      # Methods available inside has_constant_queries. A resolving block gets
+      # its own context and example, so its lets apply to that check only;
+      # every other check shares one example and one build of default_objects.
+      module Declaration
+        EXAMPLE = "issues the same SQL statements for 2 and 3 objects"
+        SHARED = "resolving with default objects"
+
+        attr_reader :constant_queries_type, :constant_queries_checks, :constant_queries_isolated,
+          :constant_queries_builders, :constant_queries_plan, :constant_queries_ledger
+
+        # Runs +checks+ in +example+, failing with every unexcepted problem at once.
+        def self.run(example, checks)
+          root = example.class.constant_queries_root
+          plan = root.constant_queries_plan
+          context = example.instance_exec(&GraphQL::ConstantQueries.config.for_schema(plan.schema).context)
+          evaluator = ->(block, *args) { example.instance_exec(*args, &block) }
+          result = Runner.call(plan, checks, evaluator: evaluator, context: context, ledger: root.constant_queries_ledger)
+          if result.hidden.size == checks.size
+            example.skip("#{checks.map(&:key).uniq.join(", ")} isn't visible in this context")
+          end
+          RSpec.fail!(result.failures.join("\n\n")) unless result.passed?
+        end
+
+        # Builds n objects for every check without its own objects.
+        def default_objects(&build)
+          unless constant_queries_root.equal?(self)
+            raise ArgumentError, "default_objects goes directly inside has_constant_queries; inside resolving, use objects"
+          end
+          raise ArgumentError, "default_objects needs a block that builds n objects" unless build
+          raise ArgumentError, "default_objects is declared twice" if @constant_queries_default_builder
+
+          @constant_queries_default_builder = build
+        end
+
+        # Builds n objects for this check instead of default_objects.
+        def objects(&build)
+          unless constant_queries_check
+            raise ArgumentError, "objects goes inside resolving; directly inside has_constant_queries, use default_objects"
+          end
+          raise ArgumentError, "objects needs a block that builds n objects" unless build
+
+          constant_queries_root.constant_queries_builders[constant_queries_check] = build
+        end
+
+        # With no keywords, customizes the field's automatic check; with
+        # keywords, adds a check passing them as the field's arguments.
+        def resolving(name, **keywords, &block)
+          raise ArgumentError, "resolving can't be nested inside another resolving" if constant_queries_check
+
+          root = constant_queries_root
+          check = Check.build(root.constant_queries_type, name, keywords)
+          if keywords.empty? && !block
+            raise ArgumentError, "#{check.description} has no arguments or block, so it changes nothing"
+          end
+          raise ArgumentError, "#{check.description} is declared twice" if root.constant_queries_checks.include?(check)
+
+          root.constant_queries_checks << check
+          return unless block
+
+          root.constant_queries_isolated << check
+          constant_queries_context(check, caller, &block)
+        end
+
+        def constant_queries_root
+          superclass.respond_to?(:constant_queries_root) ? superclass.constant_queries_root : self
+        end
+
+        def constant_queries_check
+          @constant_queries_check ||
+            (superclass.constant_queries_check if superclass.respond_to?(:constant_queries_check))
+        end
+
+        # +location+ is the has_constant_queries call site, reported for automatic checks.
+        def constant_queries_declare(type, schema, location, &declare)
+          exceptions = Exceptions.for(schema)
+          @constant_queries_type = type
+          @constant_queries_checks = []
+          @constant_queries_isolated = []
+          @constant_queries_builders = {}
+          class_exec(&declare)
+          raise ArgumentError, "has_constant_queries needs default_objects { |n| ... }" unless @constant_queries_default_builder
+
+          add_automatic_checks
+          @constant_queries_plan = Plan.new(
+            type: type, schema: schema, checks: @constant_queries_checks.dup.freeze,
+            default_builder: @constant_queries_default_builder, builders: @constant_queries_builders.dup.freeze
+          )
+          add_shared_example(location)
+
+          root = self
+          before(:context) { root.instance_variable_set(:@constant_queries_ledger, Ledger.new(exceptions)) }
+          after(:context) do
+            report = root.constant_queries_ledger.stale_report(root.constant_queries_plan.checks)
+            RSpec.fail!(report) if report
+          end
+        end
+
+        # A no-argument check for every field resolving didn't already
+        # customize, skipping fields with required arguments that have checks.
+        private def add_automatic_checks
+          @constant_queries_type.fields.each_value do |field|
+            check = Check.new(type: @constant_queries_type, field: field, keywords: {}, arguments: {})
+            declared = @constant_queries_checks.select { |c| c.field == field }
+            next if declared.include?(check) || (check.requires_arguments? && declared.any?)
+
+            @constant_queries_checks << check
+          end
+        end
+
+        # One example for every check without a resolving block of its own.
+        private def add_shared_example(location)
+          shared = @constant_queries_checks - @constant_queries_isolated
+          return if shared.empty?
+
+          context(SHARED, caller: location) do
+            it(EXAMPLE, caller: location) { Declaration.run(self, shared) }
+          end
+        end
+
+        # +location+ is the backtrace RSpec reports and reruns the check by.
+        private def constant_queries_context(check, location, &block)
+          context(check.description, caller: location) do
+            @constant_queries_check = check
+            class_exec(&block)
+            it(EXAMPLE, caller: location) { Declaration.run(self, [check]) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/graphql/constant_queries/rspec/dsl.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module ConstantQueries
+    module RSpec
+      # has_constant_queries for every example group, and check B's "declares
+      # has_constant_queries" example in each inventory type's conventional spec.
+      module Dsl
+        def self.extended(group)
+          return unless group.superclass == ::RSpec::Core::ExampleGroup
+          return unless group.described_class.is_a?(Class) && group.described_class < GraphQL::Schema::Object
+
+          entry = Inventory.entry_for(group.described_class)
+          return unless entry && Pathname(group.metadata[:absolute_file_path]) == entry.spec_path
+
+          group.it("declares has_constant_queries") do
+            next if self.class.constant_queries_declared?
+
+            RSpec.fail!("#{entry.type.name} has no constant queries declaration; add " \
+              "`has_constant_queries { default_objects { |n| ... } }` to this describe block")
+          end
+        end
+
+        # Checks that every field of described_class issues the same SQL
+        # statements for 2 objects as for 3. +schema+ defaults to the type's
+        # inventory entry's.
+        def has_constant_queries(schema: nil, &declare)
+          unless superclass == ::RSpec::Core::ExampleGroup
+            raise ArgumentError, "call has_constant_queries at the top level of the describe block"
+          end
+          raise ArgumentError, "has_constant_queries needs a block: { default_objects { |n| ... } }" unless declare
+          raise ArgumentError, "has_constant_queries can only be declared once" if @constant_queries_declared
+
+          type = described_class
+          schema ||= Inventory.entry_for(type)&.schema
+          raise ArgumentError, "#{type.inspect} isn't a type of any registered schema; pass schema:" unless schema
+
+          @constant_queries_declared = true
+          location = caller
+          describe("has constant queries", caller: location) do
+            extend Declaration
+
+            constant_queries_declare(type, schema, location, &declare)
+          end
+        end
+
+        def constant_queries_declared?
+          @constant_queries_declared
+        end
+      end
+    end
+  end
+end

data/lib/graphql/constant_queries/rspec/schema_dsl.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module ConstantQueries
+    module RSpec
+      # has_specs_for_all_types, for groups describing a registered schema.
+      module SchemaDsl
+        # Check A: fails with every type of described_class without a spec file
+        # at its expected path. +except+ is a Regexp, or an array of them,
+        # matched against type names.
+        def has_specs_for_all_types(except: [])
+          Array(except).each do |pattern|
+            raise ArgumentError, "except takes Regexps, not #{pattern.inspect}" unless pattern.is_a?(Regexp)
+          end
+          schema = described_class
+          it("has a spec for every type", caller: caller) do
+            missing = Inventory.missing_specs(schema, except: except)
+            RSpec.fail!("Missing type specs:\n#{missing.map { |line| "  #{line}" }.join("\n")}") if missing.any?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/graphql/constant_queries/rspec.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "rspec/core"
+require "rspec/expectations"
+require "graphql/constant_queries"
+require_relative "rspec/declaration"
+require_relative "rspec/dsl"
+require_relative "rspec/schema_dsl"
+
+module GraphQL
+  module ConstantQueries
+    # RSpec adapter: has_constant_queries in type specs, has_specs_for_all_types in schema specs.
+    module RSpec
+      def self.fail!(message)
+        raise ::RSpec::Expectations::ExpectationNotMetError,
+          "#{message}\n\nSee #{GraphQL::ConstantQueries.config.docs_url}"
+      end
+    end
+  end
+end
+
+# Registration must happen before spec files load: RSpec applies the filter
+# when each group is defined.
+RSpec.configure do |config|
+  config.extend GraphQL::ConstantQueries::RSpec::Dsl
+  config.extend GraphQL::ConstantQueries::RSpec::SchemaDsl,
+    described_class: ->(klass) { GraphQL::ConstantQueries.config.registered?(klass) }
+end

data/lib/graphql/constant_queries/runner.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module ConstantQueries
+    # Runs a plan's checks against objects its builders make.
+    module Runner
+      # +evaluator+ calls a block with arguments in the test's scope, e.g.
+      # ->(block, *args) { example.instance_exec(*args, &block) }.
+      def self.call(plan, checks, evaluator:, context:, ledger:)
+        harness = Harness.new(schema: plan.schema, type: plan.type, context: context)
+        fields = checks.to_h { |check| [check, harness.visible_field(check.field.graphql_name)] }.compact
+        problems = {}
+        fields.group_by { |check, _field| plan.builder_for(check) }.each do |builder, pairs|
+          problems.merge!(run(harness, pairs, builder, evaluator))
+        end
+        failures = problems.filter_map { |check, problem| ledger.record(check, problem) }
+        Result.new(problems: problems, failures: failures, hidden: checks - fields.keys)
+      end
+
+      # Reloader refreshes records between runs; anything else can keep state
+      # an earlier check memoized, so each check gets its own build.
+      private_class_method def self.run(harness, pairs, builder, evaluator)
+        build = -> { [1, 2, 3].index_with { |n| evaluator.call(builder, n) } }
+        objects_by_n = build.call
+        reusable = objects_by_n.values.flatten.all? { |object| Reloader.reloadable?(object) }
+        pairs.each_with_index.to_h do |(check, field), index|
+          objects_by_n = build.call unless index.zero? || reusable
+          [check, harness.problem(field, check.arguments_with(evaluator), objects_by_n)]
+        end
+      end
+    end
+  end
+end

data/lib/graphql/constant_queries/statement_log.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module ConstantQueries
+    # Records SQL statements issued inside a block, skipping schema lookups,
+    # transaction control, and query-cache hits.
+    class StatementLog
+      IGNORED_NAMES = /SCHEMA|SAVEPOINT|TRANSACTION/
+
+      attr_reader :statements
+
+      def self.normalize(sql)
+        sql
+          .gsub(/'(?:[^']|'')*'/, "?")
+          .gsub(/\b\d+\b/, "?")
+          .gsub(/\(\s*\$?\?(?:\s*,\s*\$?\?)*\s*\)/, "(...)")
+          .squish
+      end
+
+      # Failure text for when the 3-object run issued a different number of
+      # statements than the 2-object run.
+      def self.growth_report(two, three)
+        more, fewer = (three.count > two.count) ? [three, two] : [two, three]
+        extra = more.growth_over(fewer)
+        extra = more.statements if extra.empty?
+        [
+          "issues SQL statements per object",
+          "  2 objects → #{two.count} statements, 3 objects → #{three.count} statements",
+          "  statements the #{more.equal?(three) ? 3 : 2}-object run issued more often:",
+          *extra.map { |sql| "    #{sql}" }
+        ].join("\n")
+      end
+
+      # The SQL without query-log comments and with each IN list sorted, so the
+      # same rows in another order match.
+      def self.canonical(sql)
+        sql
+          .gsub(%r{/\*.*?\*/}m, "")
+          .gsub(/\bIN \(([^()]*)\)/) { "IN (#{$1.split(/\s*,\s*/).sort.join(", ")})" }
+          .squish
+      end
+
+      def initialize
+        @statements = []
+        @seen = Set.new
+      end
+
+      def record(&block)
+        callback = ->(*, payload) { @statements << payload[:sql] unless ignored?(payload) }
+        ActiveSupport::Notifications.subscribed(callback, "sql.active_record", &block)
+      end
+
+      def count
+        statements.size
+      end
+
+      def growth_over(baseline)
+        mine = normalized_tally
+        theirs = baseline.normalized_tally
+        mine.select { |sql, n| n > theirs.fetch(sql, 0) }.keys
+      end
+
+      protected def normalized_tally
+        statements.map { |sql| self.class.normalize(sql) }.tally
+      end
+
+      # The query cache only matches identical SQL, so a repeat with its IN list
+      # in another order (e.g. ids sorted by a random name) is skipped as a hit.
+      private def ignored?(payload)
+        payload[:cached] || IGNORED_NAMES.match?(payload[:name].to_s) ||
+          !@seen.add?([self.class.canonical(payload[:sql]), binds(payload)])
+      end
+
+      # Bound values, so one SQL text run for different ids counts each time.
+      private def binds(payload)
+        binds = payload[:type_casted_binds]
+        binds = binds.respond_to?(:call) ? binds.call : binds
+        Array(binds).map(&:to_s).sort
+      end
+    end
+  end
+end

data/lib/graphql/constant_queries/test_schema.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module ConstantQueries
+    # A subclass of +schema+ whose only root field returns
+    # context[OBJECTS_KEY] as +type+. Items are nullable so unauthorized
+    # objects come back as nulls instead of errors.
+    module TestSchema
+      OBJECTS_KEY = :constant_queries_objects
+
+      def self.for(schema, type)
+        @cache ||= {}
+        @cache[[schema, type]] ||= Class.new(schema) do
+          # graphql-ruby doesn't inherit dataloader_class; without this every source runs unbatched.
+          self.dataloader_class = schema.dataloader_class
+          query(
+            Class.new(GraphQL::Schema::Object) do
+              graphql_name "ConstantQueriesRoot"
+              field :objects, [type, {null: true}], null: false
+
+              def objects
+                context[TestSchema::OBJECTS_KEY]
+              end
+            end
+          )
+        end
+      end
+    end
+  end
+end

data/lib/graphql/constant_queries/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module ConstantQueries
+    VERSION = "0.1.0"
+  end
+end

data/lib/graphql/constant_queries.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "yaml"
+require "active_record"
+require "active_support/core_ext/enumerable"
+require "active_support/core_ext/object/blank"
+require "active_support/core_ext/string/filters"
+require "active_support/core_ext/string/inflections"
+require "graphql"
+
+require_relative "constant_queries/version"
+
+module GraphQL
+  # Proves every field of every object type issues the same SQL statements
+  # for 2 objects as for 3.
+  module ConstantQueries
+    Error = Class.new(StandardError)
+    ConfigurationError = Class.new(Error)
+
+    README_URL = "https://github.com/stevecrozz/graphql-constant_queries#readme"
+
+    def self.config
+      @config ||= Configuration.new
+    end
+
+    def self.configure
+      yield config
+      reset_caches!
+      config
+    end
+
+    # Forgets the configuration and everything derived from it.
+    def self.reset!
+      @config = nil
+      reset_caches!
+    end
+
+    def self.reset_caches!
+      Inventory.reset! if const_defined?(:Inventory)
+      Exceptions.reset! if const_defined?(:Exceptions)
+    end
+  end
+end
+
+require_relative "constant_queries/configuration"
+require_relative "constant_queries/statement_log"
+require_relative "constant_queries/reloader"
+require_relative "constant_queries/test_schema"
+require_relative "constant_queries/operation_builder"
+require_relative "constant_queries/harness"
+require_relative "constant_queries/inventory"
+require_relative "constant_queries/check"
+require_relative "constant_queries/exceptions"
+require_relative "constant_queries/ledger"
+require_relative "constant_queries/plan"
+require_relative "constant_queries/result"
+require_relative "constant_queries/runner"

metadata

@@ -0,0 +1,109 @@
+--- !ruby/object:Gem::Specification
+name: graphql-constant_queries
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Stephen Crosby
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-10-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: graphql
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.5'
+description: Generates a check for every field of every object type in a graphql-ruby
+  schema that fails when the field's ActiveRecord statement count grows with the number
+  of objects it resolves across.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/graphql/constant_queries.rb
+- lib/graphql/constant_queries/check.rb
+- lib/graphql/constant_queries/configuration.rb
+- lib/graphql/constant_queries/exceptions.rb
+- lib/graphql/constant_queries/harness.rb
+- lib/graphql/constant_queries/inventory.rb
+- lib/graphql/constant_queries/ledger.rb
+- lib/graphql/constant_queries/operation_builder.rb
+- lib/graphql/constant_queries/plan.rb
+- lib/graphql/constant_queries/reloader.rb
+- lib/graphql/constant_queries/result.rb
+- lib/graphql/constant_queries/rspec.rb
+- lib/graphql/constant_queries/rspec/declaration.rb
+- lib/graphql/constant_queries/rspec/dsl.rb
+- lib/graphql/constant_queries/rspec/schema_dsl.rb
+- lib/graphql/constant_queries/runner.rb
+- lib/graphql/constant_queries/statement_log.rb
+- lib/graphql/constant_queries/test_schema.rb
+- lib/graphql/constant_queries/version.rb
+homepage: https://github.com/stevecrozz/graphql-constant_queries
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  source_code_uri: https://github.com/stevecrozz/graphql-constant_queries
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Prove every graphql-ruby field issues a constant number of SQL statements
+test_files: []