bullematic 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5e3046689e0ebe235c6c512c31f7ad7c6252dadb773a576f81bbad8d2e6010e7
-  data.tar.gz: 10dff920eed6301bf55440c13530ad424cf64f29fa25344da634d7bd4ffe58df
+  metadata.gz: 491dc6d6f03d8043bbd7799463e7626a821cf22984bd90afcd15526184912214
+  data.tar.gz: d968aec38e36c5a90b548dfd654a2917e6faf1ce54d9cf34c3736d1a759a4952
 SHA512:
-  metadata.gz: 8bc920365f940b1fdd4f5953d7b3c62a5bd2ca5094c99b22ec77122b69d44b8051985b003a0d9aa0b2963d1ba2ce13d88b324187c1aaf04d5170d9effe81b324
-  data.tar.gz: 04ba28c1ea4ab1f335b5711e93b33cb6826b62240dc4b19039a654cb21099f0e449fb5ddf08c4443a40c364659c5accb33df47d11663748092f5d1651c43a496
+  metadata.gz: f49686338aab777ebd78762a8fb1f35729e2ed1d0ee229ed8dc341ffb4a0207ac169ff988783b0c7839ace99c615295fec816f78185f89502dc4981f0b60553b
+  data.tar.gz: f9c57f50dbceb5e8fbd26198c0c3549cd26f0c9e15e6beafb59992f788afd68ac138f49f84d20d3b7adcacbc4eed9a8c04facabf55ab0e2bf17fc9246cdf7104

data/CHANGELOG.md

@@ -5,7 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.2.0] - 2026-08-29
+
+### Added
+
+- Add a `bullematic` executable with explicit `record`, `plan`, `apply`, `verify`, `fix`, and `doctor` commands. Recorded evidence and commands persist across processes, and verification reruns the recorded command to confirm that N+1 warnings are gone.
+- Support high-confidence fixes for direct Active Record queries assigned to local variables, namespaced models, and structurally verified nested associations.
+
+### Changed
+
+- Disable source writes by default: automatic fixing is off, dry-run planning is on, and backups are enabled. Ambiguous, dynamic, or unverifiable query origins and associations are skipped instead of guessed.
+- Record detections without retaining or applying them during normal Rails requests; source changes now require an explicit command or configuration.
+- Support Bullet 6.x through 8.x and report installed dependency compatibility through `bullematic doctor`.
+
+### Fixed
+
+- Preserve and deduplicate detections across complete RSpec and Minitest runs, and capture Rails notifications before Bullet clears them.
+- Preserve existing eager-loading arguments, multibyte and legacy source encodings, and line endings while rejecting generated Ruby with invalid syntax.
+- Reject stale, missing, read-only, symlinked, or newly excluded sources and unsafe backup paths, and replace files atomically on Unix and Windows without changing their permissions.
 
 ## [0.1.0] - 2026-01-13
 

data/README.md

@@ -5,7 +5,7 @@
 
 <p align="center">
   <a href="https://badge.fury.io/rb/bullematic"><img src="https://badge.fury.io/rb/bullematic.svg" alt="Gem Version"></a>
-  <a href="https://github.com/ydah/bullematic/actions/workflows/main.yml"><img src="https://github.com/ydah/bullematic/actions/workflows/main.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/ydah/bullematic/actions/workflows/test.yml"><img src="https://github.com/ydah/bullematic/actions/workflows/test.yml/badge.svg" alt="CI"></a>
 </p>
 
 <p align="center">
@@ -23,7 +23,7 @@ Bullematic hooks into [Bullet](https://github.com/flyerhzm/bullet) notifications
 
 ## Features
 
-- Automatic N+1 fixes for Rails scopes and queries
+- High-confidence N+1 fixes for direct Active Record queries
 - Runtime capture via Bullet notifications
 - AST-based rewrites powered by Prism
 - Dry-run mode and optional backups
@@ -46,7 +46,7 @@ bundle install
 ## Requirements
 
 - Ruby 3.1+
-- Bullet 6.0+
+- Bullet 6.0 through 8.x
 
 ## Quick Start
 
@@ -61,18 +61,29 @@ Bullematic.configure do |config|
   config.auto_fix = true
   config.target_paths = %w[app/controllers app/models app/services]
   config.skip_paths = %w[app/controllers/admin]
-  config.dry_run = false  # Set to true to preview changes without applying
+  config.dry_run = true  # Preview changes before explicitly enabling writes
   config.fix_strategy = :includes  # :includes, :preload, or :eager_load
   config.backup = true  # Create backup files before modifying
 end
 ```
 
+After reviewing the planned changes, set `dry_run = false` to apply them. Ambiguous or unverifiable detections are skipped.
+
 2. Enable Bullematic at runtime:
 
 ```bash
 BULLEMATIC=1 bundle exec rspec
 ```
 
+Or use the explicit record/apply workflow:
+
+```bash
+bundle exec bullematic record -- bundle exec rspec spec/requests/posts_spec.rb
+bundle exec bullematic plan
+bundle exec bullematic apply
+bundle exec bullematic verify
+```
+
 ## Integrations
 
 ### RSpec
@@ -104,17 +115,18 @@ end
 ### Rails
 
 Bullematic auto-loads via Railtie in development and test environments when the gem is loaded.
+The development middleware records detections before Bullet clears its request collector when run through `bullematic record`; it never retains or rewrites detections inside a normal web request.
 
 ## Configuration
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `enabled` | Boolean | `true` | Enable or disable Bullematic |
-| `auto_fix` | Boolean | `true` | Automatically apply fixes |
+| `auto_fix` | Boolean | `false` | Automatically apply fixes |
 | `target_paths` | Array | `['app/controllers', 'app/models', 'app/services']` | Paths to consider for fixes |
 | `skip_paths` | Array | `[]` | Paths to skip |
-| `dry_run` | Boolean | `false` | Preview changes without applying |
-| `backup` | Boolean | `false` | Create `.bullematic.bak` backup files |
+| `dry_run` | Boolean | `true` | Preview changes without applying |
+| `backup` | Boolean | `true` | Create `.bullematic.bak` backup files |
 | `fix_strategy` | Symbol | `:includes` | Strategy: `:includes`, `:preload`, or `:eager_load` |
 | `logger` | Logger | Auto-configured | Custom logger instance |
 | `debug` | Boolean | `false` | Enable debug mode (raises errors) |
@@ -124,9 +136,9 @@ Bullematic auto-loads via Railtie in development and test environments when the
 1. Bullet detects an N+1 query during request or test execution
 2. Bullematic captures the notification and stack trace
 3. At the end of the run, Bullematic parses the file with Prism
-4. The AST finder locates the query that triggered the N+1
+4. The AST finder requires an exact query location or traces the accessed relation variable to one query
 5. The AST rewriter inserts the appropriate `includes` call
-6. The file is written back (or logged in dry-run mode)
+6. The file is parsed again and atomically replaced (or logged in dry-run mode)
 
 ### Example Transformation
 
@@ -152,8 +164,8 @@ end
 
 ## Limitations
 
-- Dynamic queries built with `send` or metaprogramming may not be fixable
-- Complex conditional branches can be hard to rewrite
+- Dynamic scopes, `send`, metaprogramming, memoized relations, and cross-method/file relation builders are skipped
+- Ambiguous query origins and associations that reflection cannot verify are skipped
 - Already-optimized queries are skipped
 
 ## Development

data/exe/bullematic

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bullematic"
+require "bullematic/cli"
+
+exit Bullematic::CLI.run(ARGV)

data/lib/bullematic/ast/finder.rb

@@ -9,9 +9,9 @@ module Bullematic
       QUERY_METHODS = %i[all where find find_by first last order limit offset].freeze #: Array[Symbol]
 
       # @rbs!
-      #   type query_location = { node: untyped, location: untyped, receiver: untyped, method_name: Symbol }
+      #   type query_location = { node: untyped, location: untyped, receiver: untyped, method_name: Symbol, target_name: Symbol? }
 
-      QueryLocation = Struct.new(:node, :location, :receiver, :method_name, keyword_init: true)
+      QueryLocation = Struct.new(:node, :location, :receiver, :method_name, :target_name, keyword_init: true)
 
       # @rbs @parse_result: untyped
 
@@ -34,12 +34,32 @@ module Bullematic
         queries
       end
 
+      # @rbs model_class_name: String
       # @rbs line_number: Integer
-      # @rbs return: QueryLocation?
-      def find_query_at_line(line_number)
-        queries = [] #: Array[QueryLocation]
-        visit_all_queries(parse_result.value, queries, line_number)
-        queries.first
+      # @rbs associations: Array[Symbol]
+      # @rbs return: Array[QueryLocation]
+      def find_model_queries_for_variables_at_line(model_class_name, line_number, associations)
+        names = association_receiver_names_at_line(parse_result.value, line_number, associations)
+        add_block_receiver_names(parse_result.value, line_number, names)
+        scope = method_scope_at_line(parse_result.value, line_number)
+        find_model_queries(model_class_name).select do |query|
+          query.target_name &&
+            names.include?(query.target_name) &&
+            !block_parameter_at_line?(parse_result.value, query.target_name, line_number) &&
+            query.location.end_line <= line_number &&
+            method_scope_at_line(parse_result.value, query.location.start_line).equal?(scope) &&
+            !variable_written_between?(scope || parse_result.value, query.target_name, query.location.end_line, line_number, scope)
+        end
+      end
+
+      # @rbs parent_association: Symbol
+      # @rbs child_associations: Array[Symbol]
+      # @rbs line_number: Integer?
+      # @rbs return: bool
+      def nested_association?(parent_association, child_associations, line_number)
+        return false unless line_number
+
+        nested_association_in_node?(parse_result.value, parent_association, child_associations, line_number)
       end
 
       private
@@ -55,7 +75,7 @@ module Bullematic
         return if skip_nodes.include?(node.object_id)
 
         case node
-        when Prism::InstanceVariableWriteNode
+        when Prism::InstanceVariableWriteNode, Prism::LocalVariableWriteNode
           if check_assignment_node(node, queries, model_class_name, target_line)
             mark_descendant_calls(node.value, skip_nodes)
           end
@@ -81,30 +101,6 @@ module Bullematic
         end
       end
 
-      # @rbs node: untyped
-      # @rbs queries: Array[QueryLocation]
-      # @rbs target_line: Integer?
-      # @rbs return: void
-      def visit_all_queries(node, queries, target_line)
-        return unless node.respond_to?(:child_nodes)
-
-        if node.is_a?(Prism::CallNode) && query_method?(node.name)
-          node_line = node.location.start_line
-          if target_line.nil? || node_line == target_line
-            queries << QueryLocation.new(
-              node: node,
-              location: node.location,
-              receiver: find_root_receiver(node),
-              method_name: node.name
-            )
-          end
-        end
-
-        node.child_nodes.compact.each do |child|
-          visit_all_queries(child, queries, target_line)
-        end
-      end
-
       # @rbs node: untyped
       # @rbs queries: Array[QueryLocation]
       # @rbs model_class_name: String
@@ -135,6 +131,7 @@ module Bullematic
 
         value = node.value
         return false unless value.is_a?(Prism::CallNode)
+        return false unless query_method?(value.name)
 
         root_receiver = find_root_receiver(value)
         return false unless model_constant?(root_receiver, model_class_name)
@@ -143,11 +140,101 @@ module Bullematic
           node: value,
           location: value.location,
           receiver: root_receiver,
-          method_name: value.name
+          method_name: value.name,
+          target_name: node.name
         )
         true
       end
 
+      # @rbs node: untyped
+      # @rbs line_number: Integer
+      # @rbs associations: Array[Symbol]
+      # @rbs return: Array[Symbol]
+      def association_receiver_names_at_line(node, line_number, associations)
+        return [] unless node.respond_to?(:child_nodes)
+
+        names = [] #: Array[Symbol]
+        if node.is_a?(Prism::CallNode) && associations.include?(node.name) && node.location.start_line == line_number
+          receiver = find_root_receiver(node)
+          if receiver.is_a?(Prism::InstanceVariableReadNode) || receiver.is_a?(Prism::LocalVariableReadNode)
+            names << receiver.name
+          end
+        end
+        node.child_nodes.compact.each do |child|
+          names.concat(association_receiver_names_at_line(child, line_number, associations))
+        end
+        names.uniq
+      end
+
+      # @rbs node: untyped
+      # @rbs line_number: Integer
+      # @rbs names: Array[Symbol]
+      # @rbs return: void
+      def add_block_receiver_names(node, line_number, names)
+        return unless node.respond_to?(:child_nodes)
+
+        if node.is_a?(Prism::CallNode) && node.block &&
+           line_number.between?(node.block.location.start_line, node.block.location.end_line)
+          parameters = node.block.parameters&.parameters&.requireds || []
+          receiver = node.receiver
+          if parameters.any? { |parameter| names.include?(parameter.name) } &&
+             (receiver.is_a?(Prism::InstanceVariableReadNode) || receiver.is_a?(Prism::LocalVariableReadNode))
+            names << receiver.name
+          end
+        end
+
+        node.child_nodes.compact.each { |child| add_block_receiver_names(child, line_number, names) }
+        names.uniq!
+      end
+
+      # @rbs node: untyped
+      # @rbs name: Symbol
+      # @rbs line_number: Integer
+      # @rbs return: bool
+      def block_parameter_at_line?(node, name, line_number)
+        return false unless node.respond_to?(:child_nodes)
+
+        if node.is_a?(Prism::CallNode) && node.block &&
+           line_number.between?(node.block.location.start_line, node.block.location.end_line)
+          parameters = node.block.parameters&.parameters&.requireds || []
+          return true if parameters.any? { |parameter| parameter.name == name }
+        end
+
+        node.child_nodes.compact.any? { |child| block_parameter_at_line?(child, name, line_number) }
+      end
+
+      # @rbs node: untyped
+      # @rbs line_number: Integer
+      # @rbs return: untyped
+      def method_scope_at_line(node, line_number)
+        return unless node.respond_to?(:child_nodes)
+        return unless line_number.between?(node.location.start_line, node.location.end_line)
+
+        node.child_nodes.compact.each do |child|
+          scope = method_scope_at_line(child, line_number)
+          return scope if scope
+        end
+        node if node.is_a?(Prism::DefNode)
+      end
+
+      # @rbs node: untyped
+      # @rbs name: Symbol
+      # @rbs start_line: Integer
+      # @rbs end_line: Integer
+      # @rbs scope: untyped
+      # @rbs return: bool
+      def variable_written_between?(node, name, start_line, end_line, scope)
+        return false unless node.respond_to?(:child_nodes)
+        return false if node.is_a?(Prism::DefNode) && !node.equal?(scope)
+
+        written = node.respond_to?(:name) && node.name == name &&
+                  node.class.name.match?(/\APrism::(?:Instance|Local)Variable(?:And|Operator|Or)?WriteNode\z/) &&
+                  node.location.start_line > start_line && node.location.start_line <= end_line
+        written || node.child_nodes.compact.any? do |child|
+          variable_written_between?(child, name, start_line, end_line, scope)
+        end
+      end
+
       # @rbs node: untyped
       # @rbs return: untyped
       def find_root_receiver(node)
@@ -160,9 +247,9 @@ module Bullematic
       # @rbs model_class_name: String
       # @rbs return: bool
       def model_constant?(node, model_class_name)
-        return false unless node.is_a?(Prism::ConstantReadNode)
+        return false unless node.is_a?(Prism::ConstantReadNode) || node.is_a?(Prism::ConstantPathNode)
 
-        node.name.to_s == model_class_name
+        node.full_name.delete_prefix("::") == model_class_name.delete_prefix("::")
       end
 
       # @rbs method_name: Symbol
@@ -170,6 +257,74 @@ module Bullematic
       def query_method?(method_name)
         QUERY_METHODS.include?(method_name)
       end
+
+      # @rbs node: untyped
+      # @rbs parent_association: Symbol
+      # @rbs child_associations: Array[Symbol]
+      # @rbs line_number: Integer
+      # @rbs return: bool
+      def nested_association_in_node?(node, parent_association, child_associations, line_number)
+        return false unless node.respond_to?(:child_nodes)
+
+        if node.is_a?(Prism::CallNode) && %i[each find_each].include?(node.name) && node.block &&
+           receiver_calls?(node.receiver, parent_association)
+          parameters = node.block.parameters&.parameters&.requireds || []
+          names = parameters.map(&:name)
+          return true if !variable_written?(node.block.body, names) && child_associations.all? do |association|
+            call_on_variable_at_line?(node.block.body, association, names, line_number)
+          end
+        end
+
+        node.child_nodes.compact.any? do |child|
+          nested_association_in_node?(child, parent_association, child_associations, line_number)
+        end
+      end
+
+      # @rbs node: untyped
+      # @rbs method_name: Symbol
+      # @rbs names: Array[Symbol]
+      # @rbs line_number: Integer
+      # @rbs return: bool
+      def call_on_variable_at_line?(node, method_name, names, line_number)
+        return false unless node.respond_to?(:child_nodes)
+
+        if node.is_a?(Prism::CallNode) && node.name == method_name && node.location.start_line == line_number
+          receiver = find_root_receiver(node)
+          return true if receiver.is_a?(Prism::LocalVariableReadNode) && names.include?(receiver.name)
+        end
+
+        if node.is_a?(Prism::CallNode) && node.block
+          parameters = node.block.parameters&.parameters&.requireds || []
+          return false if parameters.any? { |parameter| parameter.respond_to?(:name) && names.include?(parameter.name) }
+        end
+
+        node.child_nodes.compact.any? do |child|
+          call_on_variable_at_line?(child, method_name, names, line_number)
+        end
+      end
+
+      # @rbs node: untyped
+      # @rbs method_name: Symbol
+      # @rbs return: bool
+      def receiver_calls?(node, method_name)
+        current = node
+        while current.is_a?(Prism::CallNode)
+          return true if current.name == method_name
+
+          current = current.receiver
+        end
+        false
+      end
+
+      # @rbs node: untyped
+      # @rbs names: Array[Symbol]
+      # @rbs return: bool
+      def variable_written?(node, names)
+        return false unless node.respond_to?(:child_nodes)
+        return true if node.is_a?(Prism::LocalVariableWriteNode) && names.include?(node.name)
+
+        node.child_nodes.compact.any? { |child| variable_written?(child, names) }
+      end
     end
   end
 end

data/lib/bullematic/ast/parser.rb

@@ -10,26 +10,10 @@ module Bullematic
       # @rbs @filepath: String?
 
       class << self
-        #: () -> Hash[String, untyped]
-        def cache
-          @cache ||= {} #: Hash[String, untyped]
-        end
-
-        #: () -> void
-        def clear_cache
-          @cache = {} #: Hash[String, untyped]
-        end
-
         # @rbs filepath: String
         # @rbs return: untyped
         def parse_file(filepath)
-          return cache[filepath] if cache.key?(filepath)
-
-          result = Prism.parse_file(filepath)
-          raise ParseError, result.errors.map(&:message).join("\n") if result.failure?
-
-          cache[filepath] = result
-          result
+          new(File.binread(filepath), filepath: filepath).parse
         end
       end
 

data/lib/bullematic/ast/rewriter.rb

@@ -25,13 +25,22 @@ module Bullematic
       end
 
       # @rbs query_location: Finder::QueryLocation
-      # @rbs associations: Array[Symbol]
-      # @rbs return: void
+      # @rbs associations: Array[untyped]
+      # @rbs return: Symbol
       def add_includes(query_location, associations)
-        return if already_has_includes?(query_location, associations)
+        associations = associations.uniq
+        return :unsupported if associations.empty?
+
+        return :already_present if already_has_includes?(query_location, associations)
 
         strategy = Bullematic.configuration&.fix_strategy || :includes
         insert_point = find_insert_point(query_location)
+        pending = @modifications.find { |mod| mod.type == :insert && mod.offset == insert_point }
+        if pending
+          pending.associations = (pending.associations + associations).uniq
+          pending.new_text = ".#{strategy}(#{format_associations(pending.associations)})"
+          return :changed
+        end
 
         assoc_string = format_associations(associations)
         new_text = ".#{strategy}(#{assoc_string})"
@@ -43,24 +52,22 @@ module Bullematic
           new_text: new_text,
           associations: associations
         )
+        :changed
       end
 
       #: () -> String
       def rewrite
         return @source if @modifications.empty?
 
+        validate_modifications!
         sorted = @modifications.sort_by { |m| -m.offset }
 
         result = @source.dup
         sorted.each do |mod|
-          case mod.type
-          when :insert
-            result.insert(mod.offset, mod.new_text)
-          when :replace
-            result[mod.offset, mod.byte_length] = mod.new_text
-          when :delete
-            result[mod.offset, mod.byte_length] = ""
-          end
+          before = result.byteslice(0, mod.offset)
+          after = result.byteslice(mod.offset + mod.byte_length..)
+          replacement = mod.type == :delete ? "" : mod.new_text
+          result = before + replacement + after
         end
 
         result
@@ -74,7 +81,7 @@ module Bullematic
         node = query_location.node
         receiver = query_location.receiver
 
-        if receiver.is_a?(Prism::ConstantReadNode)
+        if receiver.is_a?(Prism::ConstantReadNode) || receiver.is_a?(Prism::ConstantPathNode)
           receiver.location.end_offset
         else
           find_chain_insert_point(node)
@@ -95,7 +102,7 @@ module Bullematic
       end
 
       # @rbs query_location: Finder::QueryLocation
-      # @rbs associations: Array[Symbol]
+      # @rbs associations: Array[untyped]
       # @rbs return: bool
       def already_has_includes?(query_location, associations)
         existing = find_existing_includes(query_location.node)
@@ -121,31 +128,86 @@ module Bullematic
       end
 
       # @rbs call_node: untyped
-      # @rbs return: Array[Symbol]
+      # @rbs return: Array[untyped]
       def extract_associations_from_call(call_node)
         return [] unless call_node.arguments
 
-        associations = [] #: Array[Symbol]
-        call_node.arguments.arguments.each do |arg|
-          case arg
-          when Prism::SymbolNode
-            associations << arg.value.to_sym
-          when Prism::ArrayNode
-            arg.elements.each do |elem|
-              associations << elem.value.to_sym if elem.is_a?(Prism::SymbolNode)
-            end
+        associations = [] #: Array[untyped]
+        call_node.arguments.arguments.each { |arg| collect_literal_associations(arg, associations) }
+        associations
+      end
+
+      # @rbs node: untyped
+      # @rbs associations: Array[untyped]
+      # @rbs return: void
+      def collect_literal_associations(node, associations)
+        case node
+        when Prism::SymbolNode
+          associations << node.value.to_sym
+        when Prism::ArrayNode
+          node.elements.each { |element| collect_literal_associations(element, associations) }
+        when Prism::KeywordHashNode, Prism::HashNode
+          association = literal_association(node)
+          associations << association if association
+        end
+      end
+
+      # @rbs node: untyped
+      # @rbs return: untyped
+      def literal_association(node)
+        case node
+        when Prism::SymbolNode
+          node.value.to_sym
+        when Prism::ArrayNode
+          values = node.elements.map { |element| literal_association(element) }
+          values unless values.any?(&:nil?)
+        when Prism::KeywordHashNode, Prism::HashNode
+          pairs = node.elements.map do |element|
+            next unless element.is_a?(Prism::AssocNode)
+
+            key = literal_association(element.key)
+            value = literal_association(element.value)
+            [key, value] if key && value
           end
+          pairs.to_h if pairs.none?(&:nil?)
         end
-        associations
       end
 
-      # @rbs associations: Array[Symbol]
+      # @rbs associations: Array[untyped]
       # @rbs return: String
       def format_associations(associations)
-        if associations.size == 1
-          ":#{associations.first}"
+        associations.map { |association| format_association(association, false) }.join(", ")
+      end
+
+      # @rbs association: untyped
+      # @rbs braces: bool
+      # @rbs return: String
+      def format_association(association, braces = true)
+        case association
+        when Hash
+          contents = association.map do |key, value|
+            key_source = key.to_s.match?(/\A[a-z_]\w*\z/) ? "#{key}:" : "#{key.inspect} =>"
+            "#{key_source} #{format_association(value)}"
+          end.join(", ")
+          braces ? "{ #{contents} }" : contents
+        when Array
+          "[#{association.map { |nested| format_association(nested) }.join(', ')}]"
         else
-          associations.map { |a| ":#{a}" }.join(", ")
+          association.inspect
+        end
+      end
+
+      #: () -> void
+      def validate_modifications!
+        @modifications.each do |modification|
+          limit = modification.offset + modification.byte_length
+          raise FixError, "edit is outside the source" if modification.offset.negative? || limit > @source.bytesize
+        end
+
+        ranges = @modifications.reject { |modification| modification.byte_length.zero? }
+        ranges.combination(2) do |left, right|
+          overlap = left.offset < right.offset + right.byte_length && right.offset < left.offset + left.byte_length
+          raise FixError, "overlapping edits" if overlap
         end
       end
     end