rails_audit_log-graphql 0.6.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a1df5ae47e9bae5cc635eb04372e8a84f3c484350f50284d98ab4602d9f2175c
-  data.tar.gz: 5bd2df5463caab8646bfab17973cd85343819b94fb189d6c3d52bbe65cbf11ce
+  metadata.gz: 681be68e65f4b6f543de2ce47434d6b547db12299d15c2f136d94f1db5b15355
+  data.tar.gz: 184994ef369aea31293293d01e22663bb1e3dc48f3e958aec6f523997ec9ed7b
 SHA512:
-  metadata.gz: 3899c333a5af6c7f9c1a05cfe1bc882f8464ad9da9d21ed677c75ce7ec6546a6181893d8a27f563822d46ed4bfb7d6f91e8349285d1bc83e3cc6aaae2a8d5147
-  data.tar.gz: cdc13b1d159a794f67fa1c46a3410b3196529dba59e234eba32147338d15e85a2478bcb676821738256792e4358100a4c07bc96cfb855c00d68db828807a1d48
+  metadata.gz: 5d06f3473ed427c34208a6067d4e77a445a10068e8ffc269f4725a858092c1a55c9dd12b504632df53e260f5e5b3b0b6c3aa8eab3a4499c475bdb165165d9403
+  data.tar.gz: a9c2936cc464d8288a815f1345b12c23918aaf7a70a15241e77e50ccf90ce0daefd27e172f1f554e7861d7d0e3d6bb9a34557cde7c614f162652795d5288a287

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 ## [Unreleased]
 
+## [1.0.0] - 2026-06-04
+
+### Added
+
+- **RSpec matcher** — `have_graphql_audit_entry(:update).touching(:title).for_type("Post")` for asserting audit entries in `Schema.execute` responses; include `RailsAuditLog::Graphql::Testing::RSpecMatchers` in your RSpec config
+- **Minitest assertions** — `assert_graphql_audit_entry` and `refute_graphql_audit_entry` with the same filter interface; include `RailsAuditLog::Graphql::Testing::MinitestAssertions` in your test class
+- Full YARD documentation on all public modules, classes, and methods
+- RBS type signatures for `Testing::RSpecMatchers` and `Testing::MinitestAssertions`
+
+### Changed
+
+- API stability guarantee — no breaking changes to public interfaces without a major version bump
+
 ## [0.6.1] - 2026-06-04
 
 ### Added

data/README.md

@@ -29,6 +29,9 @@ A [graphql-ruby](https://graphql-ruby.org) API layer for the [`rails_audit_log`]
     - [AuditLogSubscriptionsMixin](#auditlogsubscriptionsmixin)
     - [auditLogEntryCreated](#auditlogentrycreated)
     - [Broadcaster](#broadcaster)
+- [Testing](#testing)
+  - [RSpec matchers](#rspec-matchers)
+  - [Minitest assertions](#minitest-assertions)
 - [Development](#development)
 - [Contributing](#contributing)
 - [License](#license)
@@ -388,6 +391,82 @@ For each entry, the broadcaster triggers:
 
 [↑ Back to top](#table-of-contents)
 
+## Testing
+
+`rails_audit_log-graphql` ships test helpers for both RSpec and Minitest so you can
+assert that your mutations actually produce the expected audit log entries.
+
+Require the testing helpers from your test helper:
+
+```ruby
+# spec/spec_helper.rb or test/test_helper.rb
+require "rails_audit_log/graphql/testing"
+```
+
+### RSpec matchers
+
+Include `RailsAuditLog::Graphql::Testing::RSpecMatchers` in your configuration:
+
+```ruby
+RSpec.configure do |config|
+  config.include RailsAuditLog::Graphql::Testing::RSpecMatchers
+end
+```
+
+Then use `have_graphql_audit_entry` against any `GraphQL::Query::Result` (or plain hash) returned by `Schema.execute`:
+
+```ruby
+result = MySchema.execute('{ auditLogEntries { event diff { attribute } } }')
+
+# Assert an entry with a specific event exists
+expect(result).to have_graphql_audit_entry(:update)
+
+# Assert the update entry touched the :title attribute
+# (requires diff { attribute } in the query)
+expect(result).to have_graphql_audit_entry(:update).touching(:title)
+
+# Scope to a specific model
+expect(result).to have_graphql_audit_entry(:create).for_type("Post")
+
+# Combine chains
+expect(result).to have_graphql_audit_entry(:update).for_type("Post").touching(:title)
+```
+
+The matcher searches `auditLogEntries` and `auditLogEntriesConnection.nodes` in the
+response data.
+
+[↑ Back to top](#table-of-contents)
+
+### Minitest assertions
+
+Include `RailsAuditLog::Graphql::Testing::MinitestAssertions` in your test class:
+
+```ruby
+class ActiveSupport::TestCase
+  include RailsAuditLog::Graphql::Testing::MinitestAssertions
+end
+```
+
+Use `assert_graphql_audit_entry` and `refute_graphql_audit_entry`:
+
+```ruby
+result = MySchema.execute('{ auditLogEntries { event diff { attribute } } }')
+
+# Assert an update entry exists
+assert_graphql_audit_entry result, event: :update
+
+# Assert an update entry that touched :title
+assert_graphql_audit_entry result, event: :update, touching: :title
+
+# Assert no destroy entry exists
+refute_graphql_audit_entry result, event: :destroy
+
+# Custom failure message
+assert_graphql_audit_entry result, event: :update, message: "mutation should have created an update entry"
+```
+
+[↑ Back to top](#table-of-contents)
+
 ## Development
 
 ```bash

data/ROADMAP.md

@@ -4,10 +4,4 @@ This gem adds a GraphQL API layer on top of [`rails_audit_log`](https://github.c
 
 ---
 
-## 1.0.0 — Stable API
-
-- Full YARD documentation
-- **RSpec matchers** — `expect(response).to have_graphql_audit_entry(:update).touching(:title)` 
-- **Minitest assertions** — `assert_graphql_audit_entry`
-- API stability guarantee — no breaking changes without a major version bump
-- Complete README with setup guide, examples, and schema reference
+_No planned milestones at this time._

data/lib/rails_audit_log/graphql/queries/audit_log_entries_query_mixin.rb

@@ -3,7 +3,24 @@
 module RailsAuditLog
   module Graphql
     module Queries
+      # Mixin that adds all audit log query fields to a host application's +QueryType+.
+      #
+      # Include in your +QueryType+:
+      #
+      #   class Types::QueryType < Types::BaseObject
+      #     include RailsAuditLog::Graphql::Queries::AuditLogEntriesQueryMixin
+      #   end
+      #
+      # This adds the following fields to the schema:
+      # - +auditLogEntry(id:)+ — fetch a single entry by ID
+      # - +auditLogEntries(...)+ — offset-paginated list with filters
+      # - +auditLogEntriesConnection(...)+ — cursor-paginated Relay connection
+      # - +auditLogEntriesCount(...)+ — count matching entries
+      # - +auditLogReify(itemType:, itemId:, at:)+ — reconstruct record state at a point in time
+      #
+      # @see https://github.com/eclectic-coding/rails_audit_log-graphql README
       module AuditLogEntriesQueryMixin
+        # @api private
         def self.included(base)
           base.field(
             :audit_log_entry,
@@ -90,6 +107,11 @@ module RailsAuditLog
           end
         end
 
+        # Resolves the +auditLogEntry+ field.
+        #
+        # @param id [String] the entry ID
+        # @param for_tenant [String, nil] optional tenant scope
+        # @return [RailsAuditLog::AuditLogEntry, nil]
         def resolve_audit_log_entry(id:, for_tenant: nil)
           check_authentication!
           tenant_id = for_tenant || RailsAuditLog.current_tenant&.call
@@ -97,17 +119,31 @@ module RailsAuditLog
           base.find_by(id: id)
         end
 
+        # Resolves the +auditLogEntries+ field.
+        #
+        # @return [ActiveRecord::Relation]
         def resolve_audit_log_entries(event: nil, item_type: nil, item_id: nil, actor_id: nil, actor_type: nil, since: nil, until_time: nil, touching: nil, order_by: nil, for_tenant: nil, page: 1, per_page: 25)
           check_authentication!
           scope = build_scope(event: event, item_type: item_type, item_id: item_id, actor_id: actor_id, actor_type: actor_type, since: since, until_time: until_time, touching: touching, order_by: order_by, for_tenant: for_tenant)
           scope.limit(per_page).offset((page - 1) * per_page)
         end
 
+        # Resolves the +auditLogEntriesConnection+ field.
+        #
+        # @return [ActiveRecord::Relation]
         def resolve_audit_log_entries_connection(event: nil, item_type: nil, item_id: nil, actor_id: nil, actor_type: nil, since: nil, until_time: nil, touching: nil, order_by: nil, for_tenant: nil)
           check_authentication!
           build_scope(event: event, item_type: item_type, item_id: item_id, actor_id: actor_id, actor_type: actor_type, since: since, until_time: until_time, touching: touching, order_by: order_by, for_tenant: for_tenant)
         end
 
+        # Resolves the +auditLogReify+ field. Returns the reconstructed attribute
+        # hash for +item_type+/+item_id+ as of +at+, or +nil+ when no entry exists.
+        #
+        # @param item_type [String]
+        # @param item_id [String]
+        # @param at [Time]
+        # @param for_tenant [String, nil]
+        # @return [Hash, nil]
         def resolve_audit_log_reify(item_type:, item_id:, at:, for_tenant: nil)
           check_authentication!
           tenant_id = for_tenant || RailsAuditLog.current_tenant&.call
@@ -121,6 +157,9 @@ module RailsAuditLog
           entry.object.present? ? entry.object.merge(to_attrs) : to_attrs
         end
 
+        # Resolves the +auditLogEntriesCount+ field.
+        #
+        # @return [Integer]
         def resolve_audit_log_entries_count(event: nil, item_type: nil, actor_type: nil, since: nil, for_tenant: nil)
           check_authentication!
           scope = RailsAuditLog::AuditLogEntry.all

data/lib/rails_audit_log/graphql/schema_plugin.rb

@@ -2,7 +2,29 @@
 
 module RailsAuditLog
   module Graphql
+    # Schema-level plugin that applies query-protection limits and enables
+    # dataloader batching in one +include+.
+    #
+    # Include in your GraphQL schema class:
+    #
+    #   class MySchema < GraphQL::Schema
+    #     include RailsAuditLog::Graphql::SchemaPlugin
+    #     query Types::QueryType
+    #   end
+    #
+    # This applies the following defaults (all overridable via
+    # {RailsAuditLog::Graphql} class-level accessors):
+    #
+    # | Setting                | Default | Description                                      |
+    # |------------------------|---------|--------------------------------------------------|
+    # | +max_complexity+       | 200     | Reject queries whose complexity exceeds this     |
+    # | +max_depth+            | 10      | Reject queries nested deeper than this           |
+    # | +default_max_page_size+| 25      | Page-size assumption for connection complexity   |
+    #
+    # Also enables +GraphQL::Dataloader+ for N+1-free batch loading of
+    # +actor.record+ and +auditedResource.record+ fields.
     module SchemaPlugin
+      # @api private
       def self.included(base)
         base.max_complexity(RailsAuditLog::Graphql.max_complexity)
         base.max_depth(RailsAuditLog::Graphql.max_depth)

data/lib/rails_audit_log/graphql/sources/record_by_id_source.rb

@@ -3,11 +3,25 @@
 module RailsAuditLog
   module Graphql
     module Sources
+      # Dataloader source that batch-loads ActiveRecord records by class name and ID,
+      # returning their +attributes+ hash.
+      #
+      # Used internally by {Types::ActorType} and {Types::AuditedResourceType} to
+      # resolve the +record+ field without N+1 queries.
+      #
+      # @example Manual use in a custom resolver
+      #   dataloader.with(RecordByIdSource, "User").load("42")
       class RecordByIdSource < GraphQL::Dataloader::Source
+        # @param class_name [String] the ActiveRecord model class name to load from
         def initialize(class_name)
           @class_name = class_name
         end
 
+        # Batch-loads records for the given IDs.
+        #
+        # @param ids [Array<String>] record IDs to load
+        # @return [Array<Hash, nil>] +attributes+ hash for each ID, or +nil+ when
+        #   the record does not exist or the class cannot be constantized
         def fetch(ids)
           klass = @class_name.safe_constantize
           return ids.map { nil } unless klass

data/lib/rails_audit_log/graphql/subscriptions/audit_log_subscriptions_mixin.rb

@@ -3,7 +3,26 @@
 module RailsAuditLog
   module Graphql
     module Subscriptions
+      # Mixin that adds the +auditLogEntryCreated+ subscription field to a host
+      # application's +SubscriptionType+.
+      #
+      # Include in your +SubscriptionType+:
+      #
+      #   class Types::SubscriptionType < Types::BaseObject
+      #     include RailsAuditLog::Graphql::Subscriptions::AuditLogSubscriptionsMixin
+      #   end
+      #
+      # The schema must also use +GraphQL::Subscriptions::ActionCableSubscriptions+:
+      #
+      #   class MySchema < GraphQL::Schema
+      #     subscription Types::SubscriptionType
+      #     use GraphQL::Subscriptions::ActionCableSubscriptions
+      #   end
+      #
+      # @see AuditLogEntryCreated
+      # @see Broadcaster
       module AuditLogSubscriptionsMixin
+        # @api private
         def self.included(base)
           base.field(
             :audit_log_entry_created,

data/lib/rails_audit_log/graphql/subscriptions/broadcaster.rb

@@ -3,25 +3,56 @@
 module RailsAuditLog
   module Graphql
     module Subscriptions
+      # Bridges +ActiveSupport::Notifications+ events emitted by
+      # +rails_audit_log+ to GraphQL subscription triggers.
+      #
+      # Start it once in an initializer after the schema is defined:
+      #
+      #   Rails.application.config.after_initialize do
+      #     RailsAuditLog::Graphql::Subscriptions::Broadcaster.new(schema: MySchema).start
+      #   end
+      #
+      # For each +rails_audit_log.entry_created+ notification the broadcaster
+      # fires two subscription triggers:
+      # - +auditLogEntryCreated(itemType:, itemId:)+ for record-specific subscribers
+      # - +auditLogEntryCreated(actorId:)+ for actor-specific subscribers (when an
+      #   actor is present on the entry)
       class Broadcaster
+        # @api private
         EVENT = "rails_audit_log.entry_created"
 
+        # @param schema [Class] the GraphQL schema class (must use
+        #   +GraphQL::Subscriptions::ActionCableSubscriptions+)
         def initialize(schema:)
           @schema = schema
           @subscriber = nil
         end
 
+        # Subscribe to +rails_audit_log.entry_created+ notifications and begin
+        # broadcasting to GraphQL subscribers. Idempotent — calling +start+ a
+        # second time replaces the previous subscriber.
+        #
+        # @return [void]
         def start
           @subscriber = ActiveSupport::Notifications.subscribe(EVENT) do |*, payload|
             broadcast(payload[:entry])
           end
         end
 
+        # Unsubscribe from +ActiveSupport::Notifications+. After calling +stop+,
+        # no further subscription triggers will fire until {#start} is called again.
+        #
+        # @return [void]
         def stop
           ActiveSupport::Notifications.unsubscribe(@subscriber) if @subscriber
           @subscriber = nil
         end
 
+        # Trigger GraphQL subscriptions for +entry+. Fires both the
+        # record-scoped and actor-scoped variants.
+        #
+        # @param entry [RailsAuditLog::AuditLogEntry] the newly created entry
+        # @return [void]
         def broadcast(entry)
           @schema.subscriptions.trigger(
             "audit_log_entry_created",

data/lib/rails_audit_log/graphql/testing/minitest_assertions.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module RailsAuditLog
+  module Graphql
+    module Testing
+      # Minitest assertions for GraphQL audit log entries.
+      #
+      # Include this module in a test class or in a shared support file:
+      #
+      #   class ActiveSupport::TestCase
+      #     include RailsAuditLog::Graphql::Testing::MinitestAssertions
+      #   end
+      #
+      # The assertions inspect the +auditLogEntries+ and +auditLogEntriesConnection.nodes+
+      # keys in the response data. To use the +touching:+ option, include +diff { attribute }+
+      # in your GraphQL query.
+      module MinitestAssertions
+        # Asserts that the GraphQL response contains at least one audit log entry
+        # matching the given criteria.
+        #
+        # @param response [Hash, GraphQL::Query::Result] the result of +Schema.execute+
+        # @param event [Symbol, String] expected event type (:create, :update, :destroy)
+        # @param touching [Symbol, String, nil] when given, requires the entry's +diff+ to
+        #   include an attribute with this name (query must include +diff { attribute }+)
+        # @param item_type [String, nil] when given, requires the entry's +itemType+ to match
+        # @param message [String, nil] custom failure message
+        #
+        # @example Assert an update entry exists
+        #   result = MySchema.execute('{ auditLogEntries { event } }')
+        #   assert_graphql_audit_entry result, event: :update
+        #
+        # @example Assert an update entry that touched :title
+        #   result = MySchema.execute('{ auditLogEntries { event diff { attribute } } }')
+        #   assert_graphql_audit_entry result, event: :update, touching: :title
+        def assert_graphql_audit_entry(response, event:, touching: nil, item_type: nil, message: nil)
+          matched = filter_entries(response, event: event, touching: touching, item_type: item_type)
+          default_msg = build_message("Expected", event, touching, item_type)
+          assert matched.any?, message || default_msg
+        end
+
+        # Asserts that the GraphQL response does NOT contain an audit log entry
+        # matching the given criteria.
+        #
+        # @param response [Hash, GraphQL::Query::Result] the result of +Schema.execute+
+        # @param event [Symbol, String] the event type to check
+        # @param touching [Symbol, String, nil] attribute name to match against +diff+
+        # @param item_type [String, nil] model class name to match against +itemType+
+        # @param message [String, nil] custom failure message
+        def refute_graphql_audit_entry(response, event:, touching: nil, item_type: nil, message: nil)
+          matched = filter_entries(response, event: event, touching: touching, item_type: item_type)
+          default_msg = build_message("Expected no", event, touching, item_type)
+          refute matched.any?, message || default_msg
+        end
+
+        private
+
+        def filter_entries(response, event:, touching:, item_type:)
+          entries = extract_graphql_entries(response)
+          matched = entries.select { |e| e["event"] == event.to_s }
+          matched = matched.select { |e| e["itemType"] == item_type.to_s } if item_type
+          if touching
+            matched = matched.select { |e| e["diff"]&.any? { |d| d["attribute"] == touching.to_s } }
+          end
+          matched
+        end
+
+        def build_message(prefix, event, touching, item_type)
+          msg = "#{prefix} GraphQL audit entry with event #{event.inspect}"
+          msg += " touching #{touching.inspect}" if touching
+          msg += " for type #{item_type.inspect}" if item_type
+          msg
+        end
+
+        def extract_graphql_entries(response)
+          data = response.respond_to?(:[]) ? (response["data"] || response[:data]) : nil
+          return [] unless data
+
+          entries = []
+          entries += Array(data["auditLogEntries"])
+          entries += Array(data.dig("auditLogEntriesConnection", "nodes"))
+          entries += Array(data.dig("auditLogEntriesConnection", "edges")).filter_map { |e| e["node"] }
+          entries
+        end
+      end
+    end
+  end
+end

data/lib/rails_audit_log/graphql/testing/rspec_matchers.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module RailsAuditLog
+  module Graphql
+    module Testing
+      # RSpec matchers for asserting GraphQL audit log entries in a query response.
+      #
+      # Include this module in your RSpec configuration to use the {#have_graphql_audit_entry}
+      # matcher:
+      #
+      #   RSpec.configure do |config|
+      #     config.include RailsAuditLog::Graphql::Testing::RSpecMatchers
+      #   end
+      #
+      # Or include it in a single example group:
+      #
+      #   RSpec.describe "audit logging" do
+      #     include RailsAuditLog::Graphql::Testing::RSpecMatchers
+      #   end
+      #
+      # The matcher inspects the +auditLogEntries+ and +auditLogEntriesConnection.nodes+
+      # keys in the response data. To use the +touching+ chain, include +diff { attribute }+
+      # in your GraphQL query.
+      module RSpecMatchers
+        # Returns a matcher that asserts a GraphQL response contains an audit log
+        # entry with the given event type.
+        #
+        # @param event [Symbol, String] expected event type (:create, :update, :destroy)
+        # @return [HaveGraphqlAuditEntry]
+        #
+        # @example Assert an update entry exists
+        #   result = MySchema.execute('{ auditLogEntries { event } }')
+        #   expect(result).to have_graphql_audit_entry(:update)
+        #
+        # @example Assert an update entry that touched :title
+        #   result = MySchema.execute('{ auditLogEntries { event diff { attribute } } }')
+        #   expect(result).to have_graphql_audit_entry(:update).touching(:title)
+        #
+        # @example Assert a create entry for a specific model
+        #   expect(result).to have_graphql_audit_entry(:create).for_type("Post")
+        def have_graphql_audit_entry(event)
+          HaveGraphqlAuditEntry.new(event.to_s)
+        end
+
+        # @api private
+        class HaveGraphqlAuditEntry
+          # @param event [String] the required event value
+          def initialize(event)
+            @event = event
+            @touching = nil
+            @item_type = nil
+          end
+
+          # Requires at least one matching entry's +diff+ to contain +attribute+.
+          # The query must include +diff { attribute }+ for this chain to work.
+          #
+          # @param attribute [Symbol, String] the changed attribute name
+          # @return [self]
+          def touching(attribute)
+            @touching = attribute.to_s
+            self
+          end
+
+          # Requires all matching entries to have +itemType+ equal to +item_type+.
+          #
+          # @param item_type [String] the ActiveRecord model class name
+          # @return [self]
+          def for_type(item_type)
+            @item_type = item_type.to_s
+            self
+          end
+
+          # @api private
+          def matches?(response)
+            @response = response
+            matched = extract_entries(response).select { |e| e["event"] == @event }
+            matched = matched.select { |e| e["itemType"] == @item_type } if @item_type
+            if @touching
+              matched = matched.select { |e| e["diff"]&.any? { |d| d["attribute"] == @touching } }
+            end
+            matched.any?
+          end
+
+          # @api private
+          def failure_message
+            "expected GraphQL response to include an audit entry with event #{@event.inspect}" \
+              "#{touching_clause}#{type_clause}, but it did not.\n" \
+              "Entries found: #{extract_entries(@response).map { |e| e["event"] }.inspect}"
+          end
+
+          # @api private
+          def failure_message_when_negated
+            "expected GraphQL response not to include an audit entry with event #{@event.inspect}" \
+              "#{touching_clause}#{type_clause}, but one was found."
+          end
+
+          private
+
+          def touching_clause
+            @touching ? " touching #{@touching.inspect}" : ""
+          end
+
+          def type_clause
+            @item_type ? " for type #{@item_type.inspect}" : ""
+          end
+
+          def extract_entries(response)
+            data = response.respond_to?(:[]) ? (response["data"] || response[:data]) : nil
+            return [] unless data
+
+            entries = []
+            entries += Array(data["auditLogEntries"])
+            entries += Array(data.dig("auditLogEntriesConnection", "nodes"))
+            entries += Array(data.dig("auditLogEntriesConnection", "edges")).filter_map { |e| e["node"] }
+            entries
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rails_audit_log/graphql/testing.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "testing/rspec_matchers"
+require_relative "testing/minitest_assertions"
+
+module RailsAuditLog
+  module Graphql
+    # Test helpers for asserting GraphQL audit log entries in query responses.
+    #
+    # Require this file from your test helper to load both RSpec matchers and
+    # Minitest assertions:
+    #
+    #   # spec/spec_helper.rb or test/test_helper.rb
+    #   require "rails_audit_log/graphql/testing"
+    #
+    # Then include the appropriate module for your test framework:
+    #
+    #   # RSpec
+    #   RSpec.configure do |config|
+    #     config.include RailsAuditLog::Graphql::Testing::RSpecMatchers
+    #   end
+    #
+    #   # Minitest
+    #   class ActiveSupport::TestCase
+    #     include RailsAuditLog::Graphql::Testing::MinitestAssertions
+    #   end
+    module Testing
+    end
+  end
+end

data/lib/rails_audit_log/graphql/version.rb

@@ -2,6 +2,6 @@
 
 module RailsAuditLog
   module Graphql
-    VERSION = "0.6.1"
+    VERSION = "1.0.0"
   end
 end

data/lib/rails_audit_log/graphql.rb

@@ -19,7 +19,24 @@ require_relative "graphql/subscriptions/audit_log_subscriptions_mixin"
 require_relative "graphql/subscriptions/broadcaster"
 require_relative "graphql/schema_plugin"
 
+# The top-level namespace for the rails_audit_log gem.
 module RailsAuditLog
+  # GraphQL API layer for rails_audit_log.
+  #
+  # Provides ready-made types, queries, subscriptions, and test helpers for
+  # exposing {https://github.com/eclectic-coding/rails_audit_log rails_audit_log}
+  # audit log entries through a graphql-ruby schema.
+  #
+  # == Configuration
+  #
+  # Override query-protection defaults in an initializer:
+  #
+  #   RailsAuditLog::Graphql.max_complexity      = 500
+  #   RailsAuditLog::Graphql.max_depth           = 15
+  #   RailsAuditLog::Graphql.default_max_page_size = 50
+  #
+  # These values are picked up by {SchemaPlugin} when it is included in the
+  # host schema.
   module Graphql
     class Error < StandardError; end
 
@@ -28,7 +45,23 @@ module RailsAuditLog
     @default_max_page_size = 25
 
     class << self
-      attr_accessor :max_complexity, :max_depth, :default_max_page_size
+      # Maximum allowed query complexity score.
+      # Queries whose field-complexity sum exceeds this value are rejected.
+      # Default: +200+.
+      # @return [Integer]
+      attr_accessor :max_complexity
+
+      # Maximum allowed query depth.
+      # Queries nested deeper than this value are rejected.
+      # Default: +10+.
+      # @return [Integer]
+      attr_accessor :max_depth
+
+      # Default maximum page size for Relay connections.
+      # Used by graphql-ruby when calculating connection complexity.
+      # Default: +25+.
+      # @return [Integer]
+      attr_accessor :default_max_page_size
     end
   end
 end

data/sig/rails_audit_log/graphql.rbs

@@ -168,5 +168,38 @@ module RailsAuditLog
         def check_authentication!: () -> void
       end
     end
+
+    module Testing
+      module RSpecMatchers
+        def have_graphql_audit_entry: (Symbol | String event) -> HaveGraphqlAuditEntry
+
+        class HaveGraphqlAuditEntry
+          def initialize: (String event) -> void
+          def touching: (Symbol | String attribute) -> self
+          def for_type: (String item_type) -> self
+          def matches?: (untyped response) -> bool
+          def failure_message: () -> String
+          def failure_message_when_negated: () -> String
+        end
+      end
+
+      module MinitestAssertions
+        def assert_graphql_audit_entry: (
+          untyped response,
+          event: Symbol | String,
+          ?touching: (Symbol | String)?,
+          ?item_type: String?,
+          ?message: String?
+        ) -> void
+
+        def refute_graphql_audit_entry: (
+          untyped response,
+          event: Symbol | String,
+          ?touching: (Symbol | String)?,
+          ?item_type: String?,
+          ?message: String?
+        ) -> void
+      end
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_audit_log-graphql
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -91,6 +91,9 @@ files:
 - lib/rails_audit_log/graphql/subscriptions/audit_log_entry_created.rb
 - lib/rails_audit_log/graphql/subscriptions/audit_log_subscriptions_mixin.rb
 - lib/rails_audit_log/graphql/subscriptions/broadcaster.rb
+- lib/rails_audit_log/graphql/testing.rb
+- lib/rails_audit_log/graphql/testing/minitest_assertions.rb
+- lib/rails_audit_log/graphql/testing/rspec_matchers.rb
 - lib/rails_audit_log/graphql/types/actor_type.rb
 - lib/rails_audit_log/graphql/types/audit_log_entry_sort_field_enum.rb
 - lib/rails_audit_log/graphql/types/audit_log_entry_type.rb