super_diff 0.10.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb5307b0f4dab85f765805443f6315ea45ec58d81f94211292326e32b98e1539
-  data.tar.gz: 3af49d5f9a3d7396828fdc6c1b74cd8e4103ff35fc2ebced5dbef15071fe0bab
+  metadata.gz: 68235a4b2f05ea4410a4ea302c711a694deb45e505cfbba35b55db583d245545
+  data.tar.gz: 9fce585d3906b2c8d51c6de0fc8b8fab9ad07ccf4570cfa149c9285d9e094046
 SHA512:
-  metadata.gz: 9aea5c125c0dbde9f754f4d0fd72dd20142cfe4f49077d9f7ab7e47994ea09297c5f58fc3cd59f564fe9534e17ae7e2a062433c03830dc3d209ee2217d503270
-  data.tar.gz: f1f31c074ce8f043f7ac72127b5bd46158433a5ec6af3a0b79250f08e276fba8d1936b5ed5a09e2134e1ee3e4087b7bec36535da556f7b0b04953690edb949b9
+  metadata.gz: 4bdecccb62f36227362f961d600d8c853c8594ad949001ac88060f292b06493424d26f4db8d70fdc25a6fa20d12453a5855b9ffab65f0d0b03441777605547ff
+  data.tar.gz: a224ae407479970b451a0d38051e57b82cba419e4c41985237bd3593315790f8c605080020d6fe53e81b4757b317e658b19cd8e9ea4b7820d571f450137bf5fa

data/README.md

@@ -8,24 +8,23 @@
 [issuehunt-badge]: https://img.shields.io/badge/sponsored_through-IssueHunt-2EC28C
 [issuehunt]: https://issuehunt.io/r/mcmire/super_diff
 
-SuperDiff is a gem that hooks into RSpec
-to intelligently display the differences between two data structures of any type.
+**SuperDiff** is a Ruby gem
+which is designed to display the differences between two objects of any type
+in a familiar and intelligent fashion.
 
 📢 **[See what's changed in recent versions.][changelog]**
 
-[changelog]: CHANGELOG.md
+[changelog]: ./CHANGELOG.md
 
 ## Introduction
 
 The primary motivation behind this gem
 is to vastly improve upon RSpec's built-in diffing capabilities.
-
-Sometimes, whenever you use a matcher such as `eq`, `match`, `include`, or `have_attributes`,
+RSpec has many nice features,
+and one of them is that whenever you use a matcher such as `eq`, `match`, `include`, or `have_attributes`,
 you will get a diff of the two data structures you are trying to match against.
 This is great if all you want to do is compare multi-line strings.
-But if you want to compare other, more "real world" kinds of values,
-such as what you might work with when developing API endpoints
-or testing methods that make database calls and return a set of model objects,
+But if you want to compare other, more "real world" kinds of values such as API or database data,
 then you are out of luck.
 Since [RSpec merely runs your `expected` and `actual` values through Ruby's PrettyPrinter library][rspec-differ-fail]
 and then performs a diff of these strings,
@@ -33,8 +32,7 @@ the output it produces leaves much to be desired.
 
 [rspec-differ-fail]: https://github.com/rspec/rspec-support/blob/c69a231d7369dd165ad7ce4742e1a2e21e3462b5/lib/rspec/support/differ.rb#L178
 
-For instance,
-let's say you wanted to compare these two hashes:
+For instance, let's say you wanted to compare these two hashes:
 
 ```ruby
 actual = {
@@ -78,7 +76,7 @@ expect(actual).to eq(expected)
 
 You would get output that looks like this:
 
-![Before super_diff](docs/before.png)
+![Before super_diff](docs/assets/before.png)
 
 What this library does
 is to provide a diff engine
@@ -87,162 +85,14 @@ and display them in a sensible way.
 So, using the example above,
 you'd get this instead:
 
-![After super_diff](docs/after.png)
-
-## Installation
-
-There are a few different ways to install `super_diff`
-depending on your type of project.
-
-### Rails apps
-
-If you're developing a Rails app,
-add the following to your Gemfile:
-
-```ruby
-group :test do
-  gem "super_diff"
-end
-```
-
-After running `bundle install`,
-add the following to your `rails_helper`:
-
-```ruby
-require "super_diff/rspec-rails"
-```
-
-### Projects using some part of Rails (e.g. ActiveModel)
-
-If you're developing an app using Hanami or Sinatra,
-or merely using a part of Rails such as ActiveModel,
-add the following to your Gemfile where appropriate:
-
-```ruby
-gem "super_diff"
-```
-
-After running `bundle install`,
-add the following to your `spec_helper`:
-
-```ruby
-require "super_diff/rspec"
-require "super_diff/active_support"
-```
-
-### Gems
-
-If you're developing a gem,
-add the following to your gemspec:
-
-```ruby
-spec.add_development_dependency "super_diff"
-```
-
-Now add the following to your `spec_helper`:
-
-```ruby
-require "super_diff/rspec"
-```
-
-## Configuration
-
-You can customize the behavior of the gem
-by adding a configuration block
-to your test helper file
-(`rails_helper` or `spec_helper`)
-which looks something like this:
-
-```ruby
-SuperDiff.configure do |config|
-  # ...
-end
-```
-
-### Customizing colors
-
-If you don't like the colors that SuperDiff uses,
-you can change them like this:
+![After super_diff](docs/assets/after.png)
 
-```ruby
-SuperDiff.configure do |config|
-  config.actual_color = :green
-  config.expected_color = :red
-  config.border_color = :yellow
-  config.header_color = :yellow
-end
-```
-
-See [eight_bit_color.rb](lib/super_diff/csi/eight_bit_color.rb)
-for the list of available colors.
-
-You can also completely disable colorized output.
-
-<!-- prettier-ignore-start -->
-```ruby
-SuperDiff.configure do |config|
-  config.color_enabled = false
-  end
-```
-<!-- prettier-ignore-end -->
+## Installation & Usage
 
-### Disabling the key
+📘 For more on how to install and use SuperDiff,
+[read the user documentation][user-docs].
 
-You can disable the key by changing the following config (default: true):
-
-<!-- prettier-ignore-start -->
-```ruby
-SuperDiff.configure do |config|
-  config.key_enabled = false
-end
-```
-<!-- prettier-ignore-end -->
-
-### Hiding unimportant lines
-
-When looking at a large diff for which many of the lines do not change,
-it can be difficult to locate the lines which do. Text-oriented
-diffs such as those you get from a conventional version control system
-solve this problem by removing those unchanged lines from the diff
-entirely. The same can be done in SuperDiff.
-
-```ruby
-SuperDiff.configure do |config|
-  config.diff_elision_enabled = false
-  config.diff_elision_maximum = 3
-end
-```
-
-- `diff_elision_enabled` — The elision logic is disabled by default so
-  as not to surprise people, so setting this to `true` will turn it on.
-- `diff_elision_maximum` — This number controls what happens to
-  unchanged lines (i.e. lines that are neither "insert" lines nor
-  "delete" lines) that are in between changed lines. If a section of
-  unchanged lines is beyond this number, the gem will elide (a fancy
-  word for remove) the data structures within that section as much as
-  possible until the limit is reached or it cannot go further. Elided
-  lines are replaced with a `# ...` marker.
-
-### Diffing custom objects
-
-If you are comparing two data structures
-that involve a class that is specific to your project,
-the resulting diff may not look as good as diffs involving native or primitive objects.
-This happens because if SuperDiff doesn't recognize a class,
-it will fall back to a generic representation when diffing instances of that class.
-Fortunately, the gem has a pluggable interface
-that allows you to insert your own implementations
-of key pieces involved in the diffing process.
-I'll have more about how that works soon,
-but here is what such a configuration would look like:
-
-```ruby
-SuperDiff.configure do |config|
-  config.add_extra_differ_class(YourDiffer)
-  config.add_extra_operation_tree_builder_class(YourOperationTreeBuilder)
-  config.add_extra_operation_tree_class(YourOperationTree)
-end
-```
+[user-docs]: ./docs/users/getting-started.md
 
 ## Support
 
@@ -257,16 +107,19 @@ I'll try to respond to it as soon as I can!
 ## Contributing
 
 Any code contributions to improve this library are welcome!
-Please see the [contributing](./CONTRIBUTING.md) document for more on how to do that.
+Please see the [contributing](./docs/contributors/index.md) document
+for more on how to do that.
 
 ## Sponsoring
 
 If there's a change you want implemented, you can choose to sponsor that change!
 `super_diff` is set up on IssueHunt,
 so feel free to search for an existing issue (or make your own)
-and [add a bounty](https://issuehunt.io/r/mcmire/super_diff).
+and [add a bounty][issuehunt].
 I'll get notified right away!
 
+[issuehunt]: https://issuehunt.io/r/mcmire/super_diff
+
 ## Compatibility
 
 `super_diff` is [tested][gh-actions] to work with

data/lib/super_diff/active_record/differs/active_record_relation.rb

@@ -1,7 +1,7 @@
 module SuperDiff
   module ActiveRecord
     module Differs
-      class ActiveRecordRelation < SuperDiff::Differs::Base
+      class ActiveRecordRelation < Core::AbstractDiffer
         def self.applies_to?(expected, actual)
           expected.is_a?(::Array) && actual.is_a?(::ActiveRecord::Relation)
         end

data/lib/super_diff/active_record/inspection_tree_builders/active_record_model.rb

@@ -0,0 +1,57 @@
+module SuperDiff
+  module ActiveRecord
+    module InspectionTreeBuilders
+      class ActiveRecordModel < Core::AbstractInspectionTreeBuilder
+        def self.applies_to?(value)
+          value.is_a?(::ActiveRecord::Base)
+        end
+
+        def id
+          object.class.primary_key
+        end
+
+        def call
+          Core::InspectionTree.new do |t1|
+            t1.as_lines_when_rendering_to_lines(
+              collection_bookend: :open
+            ) do |t2|
+              t2.add_text "#<#{object.class} "
+
+              # stree-ignore
+              t2.when_rendering_to_lines do |t3|
+                  t3.add_text "{"
+                end
+            end
+
+            t1.nested do |t2|
+              t2.insert_separated_list(
+                [id] + (object.attributes.keys.sort - [id])
+              ) do |t3, name|
+                t3.as_prefix_when_rendering_to_lines do |t4|
+                  t4.add_text "#{name}: "
+                end
+
+                if name == id
+                  t3.add_inspection_of object.id
+                else
+                  t3.add_inspection_of object.read_attribute(name)
+                end
+              end
+            end
+
+            t1.as_lines_when_rendering_to_lines(
+              collection_bookend: :close
+            ) do |t2|
+              # stree-ignore
+              t2.when_rendering_to_lines do |t3|
+                  t3.add_text "}"
+                end
+
+              t2.add_text ">"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/super_diff/active_record/inspection_tree_builders/active_record_relation.rb

@@ -0,0 +1,34 @@
+module SuperDiff
+  module ActiveRecord
+    module InspectionTreeBuilders
+      class ActiveRecordRelation < Core::AbstractInspectionTreeBuilder
+        def self.applies_to?(value)
+          value.is_a?(::ActiveRecord::Relation)
+        end
+
+        def call
+          Core::InspectionTree.new do |t1|
+            # stree-ignore
+            t1.as_lines_when_rendering_to_lines(
+                collection_bookend: :open
+              ) do |t2|
+                t2.add_text "#<ActiveRecord::Relation ["
+              end
+
+            # stree-ignore
+            t1.nested do |t2|
+                t2.insert_array_inspection_of(object)
+              end
+
+            # stree-ignore
+            t1.as_lines_when_rendering_to_lines(
+                collection_bookend: :close
+              ) do |t2|
+                t2.add_text "]>"
+              end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/super_diff/active_record/inspection_tree_builders.rb

@@ -0,0 +1,14 @@
+module SuperDiff
+  module ActiveRecord
+    module InspectionTreeBuilders
+      autoload(
+        :ActiveRecordModel,
+        "super_diff/active_record/inspection_tree_builders/active_record_model"
+      )
+      autoload(
+        :ActiveRecordRelation,
+        "super_diff/active_record/inspection_tree_builders/active_record_relation"
+      )
+    end
+  end
+end

data/lib/super_diff/active_record/monkey_patches.rb

@@ -1,9 +1,12 @@
 # rubocop:disable Style/BracesAroundHashParameters, Style/ClassAndModuleChildren
 class ActiveRecord::Base
+  # TODO: Remove this monkey patch if possible
   def attributes_for_super_diff
-    (attributes.keys.sort - ["id"]).reduce({ id: id }) do |hash, key|
-      hash.merge(key.to_sym => attributes[key])
-    end
+    id_attr = self.class.primary_key
+
+    (attributes.keys.sort - [id_attr]).reduce(
+      { id_attr.to_sym => id }
+    ) { |hash, key| hash.merge(key.to_sym => attributes[key]) }
   end
 end
 # rubocop:enable Style/BracesAroundHashParameters, Style/ClassAndModuleChildren

data/lib/super_diff/active_record/object_inspection.rb

@@ -1,10 +1,22 @@
 module SuperDiff
   module ActiveRecord
     module ObjectInspection
-      autoload(
-        :InspectionTreeBuilders,
-        "super_diff/active_record/object_inspection/inspection_tree_builders"
-      )
+      module InspectionTreeBuilders
+        def self.const_missing(missing_const_name)
+          if ActiveRecord::InspectionTreeBuilders.const_defined?(
+               missing_const_name
+             )
+            warn <<~EOT
+              WARNING: SuperDiff::ActiveRecord::ObjectInspection::InspectionTreeBuilders::#{missing_const_name} is deprecated and will be removed in the next major release.
+              Please use SuperDiff::ActiveRecord::InspectionTreeBuilders::#{missing_const_name} instead.
+              #{caller_locations.join("\n")}
+            EOT
+            ActiveRecord::InspectionTreeBuilders.const_get(missing_const_name)
+          else
+            super
+          end
+        end
+      end
     end
   end
 end

data/lib/super_diff/active_record/operation_tree_builders/active_record_model.rb

@@ -1,7 +1,7 @@
 module SuperDiff
   module ActiveRecord
     module OperationTreeBuilders
-      class ActiveRecordModel < SuperDiff::OperationTreeBuilders::CustomObject
+      class ActiveRecordModel < Basic::OperationTreeBuilders::CustomObject
         def self.applies_to?(expected, actual)
           expected.is_a?(::ActiveRecord::Base) &&
             actual.is_a?(::ActiveRecord::Base) && expected.class == actual.class
@@ -9,8 +9,12 @@ module SuperDiff
 
         protected
 
+        def id
+          expected.class.primary_key
+        end
+
         def attribute_names
-          ["id"] + (expected.attributes.keys.sort - ["id"])
+          [id] + (expected.attributes.keys.sort - [id])
         end
       end
     end

data/lib/super_diff/active_record/operation_tree_builders/active_record_relation.rb

@@ -1,7 +1,7 @@
 module SuperDiff
   module ActiveRecord
     module OperationTreeBuilders
-      class ActiveRecordRelation < SuperDiff::OperationTreeBuilders::Array
+      class ActiveRecordRelation < Basic::OperationTreeBuilders::Array
         def self.applies_to?(expected, actual)
           expected.is_a?(::Array) && actual.is_a?(::ActiveRecord::Relation)
         end

data/lib/super_diff/active_record/operation_tree_flatteners/active_record_relation.rb

@@ -1,7 +1,7 @@
 module SuperDiff
   module ActiveRecord
     module OperationTreeFlatteners
-      class ActiveRecordRelation < SuperDiff::OperationTreeFlatteners::Collection
+      class ActiveRecordRelation < Basic::OperationTreeFlatteners::Collection
         protected
 
         def open_token

data/lib/super_diff/active_record/operation_trees/active_record_relation.rb

@@ -1,7 +1,7 @@
 module SuperDiff
   module ActiveRecord
     module OperationTrees
-      class ActiveRecordRelation < SuperDiff::OperationTrees::Array
+      class ActiveRecordRelation < Basic::OperationTrees::Array
         def self.applies_to?(value)
           value.is_a?(ActiveRecord::Relation)
         end

data/lib/super_diff/active_record.rb

@@ -1,28 +1,24 @@
 require "super_diff/active_support"
 
+require "super_diff/active_record/differs"
+require "super_diff/active_record/inspection_tree_builders"
+require "super_diff/active_record/operation_trees"
+require "super_diff/active_record/operation_tree_builders"
+require "super_diff/active_record/operation_tree_flatteners"
+
 module SuperDiff
   module ActiveRecord
-    autoload :Differs, "super_diff/active_record/differs"
-    autoload(:ObjectInspection, "super_diff/active_record/object_inspection")
-    autoload(:OperationTrees, "super_diff/active_record/operation_trees")
-    autoload(
-      :OperationTreeBuilders,
-      "super_diff/active_record/operation_tree_builders"
-    )
-    autoload(
-      :OperationTreeFlatteners,
-      "super_diff/active_record/operation_tree_flatteners"
-    )
+    autoload :ObjectInspection, "super_diff/active_record/object_inspection"
 
     SuperDiff.configure do |config|
-      config.add_extra_differ_classes(Differs::ActiveRecordRelation)
-      config.add_extra_operation_tree_builder_classes(
+      config.prepend_extra_differ_classes(Differs::ActiveRecordRelation)
+      config.prepend_extra_operation_tree_builder_classes(
         OperationTreeBuilders::ActiveRecordModel,
         OperationTreeBuilders::ActiveRecordRelation
       )
-      config.add_extra_inspection_tree_builder_classes(
-        ObjectInspection::InspectionTreeBuilders::ActiveRecordModel,
-        ObjectInspection::InspectionTreeBuilders::ActiveRecordRelation
+      config.prepend_extra_inspection_tree_builder_classes(
+        InspectionTreeBuilders::ActiveRecordModel,
+        InspectionTreeBuilders::ActiveRecordRelation
       )
     end
   end

data/lib/super_diff/active_support/differs/hash_with_indifferent_access.rb

@@ -1,7 +1,7 @@
 module SuperDiff
   module ActiveSupport
     module Differs
-      class HashWithIndifferentAccess < SuperDiff::Differs::Hash
+      class HashWithIndifferentAccess < Basic::Differs::Hash
         def self.applies_to?(expected, actual)
           (
             expected.is_a?(::HashWithIndifferentAccess) && actual.is_a?(::Hash)

data/lib/super_diff/active_support/inspection_tree_builders/hash_with_indifferent_access.rb

@@ -0,0 +1,44 @@
+module SuperDiff
+  module ActiveSupport
+    module InspectionTreeBuilders
+      class HashWithIndifferentAccess < Core::AbstractInspectionTreeBuilder
+        def self.applies_to?(value)
+          value.is_a?(::HashWithIndifferentAccess)
+        end
+
+        def call
+          Core::InspectionTree.new do |t1|
+            # stree-ignore
+            t1.as_lines_when_rendering_to_lines(
+                collection_bookend: :open
+              ) do |t2|
+                t2.add_text "#<HashWithIndifferentAccess {"
+              end
+
+            # stree-ignore
+            t1.when_rendering_to_string do |t2|
+                t2.add_text " "
+              end
+
+            # stree-ignore
+            t1.nested do |t2|
+                t2.insert_hash_inspection_of(object)
+              end
+
+            # stree-ignore
+            t1.when_rendering_to_string do |t2|
+                t2.add_text " "
+              end
+
+            # stree-ignore
+            t1.as_lines_when_rendering_to_lines(
+                collection_bookend: :close
+              ) do |t2|
+                t2.add_text "}>"
+              end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/super_diff/active_support/inspection_tree_builders/ordered_options.rb

@@ -0,0 +1,44 @@
+module SuperDiff
+  module ActiveSupport
+    module InspectionTreeBuilders
+      class OrderedOptions < Basic::InspectionTreeBuilders::Hash
+        def self.applies_to?(value)
+          value.is_a?(::ActiveSupport::OrderedOptions)
+        end
+
+        def call
+          Core::InspectionTree.new do |t1|
+            # stree-ignore
+            t1.as_lines_when_rendering_to_lines(
+                collection_bookend: :open
+              ) do |t2|
+                t2.add_text "#<OrderedOptions {"
+              end
+
+            # stree-ignore
+            t1.when_rendering_to_string do |t2|
+                t2.add_text " "
+              end
+
+            # stree-ignore
+            t1.nested do |t2|
+                t2.insert_hash_inspection_of(object.to_hash)
+              end
+
+            # stree-ignore
+            t1.when_rendering_to_string do |t2|
+                t2.add_text " "
+              end
+
+            # stree-ignore
+            t1.as_lines_when_rendering_to_lines(
+                collection_bookend: :close
+              ) do |t2|
+                t2.add_text "}>"
+              end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/super_diff/active_support/inspection_tree_builders.rb

@@ -0,0 +1,14 @@
+module SuperDiff
+  module ActiveSupport
+    module InspectionTreeBuilders
+      autoload(
+        :HashWithIndifferentAccess,
+        "super_diff/active_support/inspection_tree_builders/hash_with_indifferent_access"
+      )
+      autoload(
+        :OrderedOptions,
+        "super_diff/active_support/inspection_tree_builders/ordered_options"
+      )
+    end
+  end
+end

data/lib/super_diff/active_support/object_inspection.rb

@@ -1,10 +1,22 @@
 module SuperDiff
   module ActiveSupport
     module ObjectInspection
-      autoload(
-        :InspectionTreeBuilders,
-        "super_diff/active_support/object_inspection/inspection_tree_builders"
-      )
+      module InspectionTreeBuilders
+        def self.const_missing(missing_const_name)
+          if ActiveSupport::InspectionTreeBuilders.const_defined?(
+               missing_const_name
+             )
+            warn <<~EOT
+              WARNING: SuperDiff::ActiveSupport::ObjectInspection::InspectionTreeBuilders::#{missing_const_name} is deprecated and will be removed in the next major release.
+              Please use SuperDiff::ActiveSupport::InspectionTreeBuilders::#{missing_const_name} instead.
+              #{caller_locations.join("\n")}
+            EOT
+            ActiveSupport::InspectionTreeBuilders.const_get(missing_const_name)
+          else
+            super
+          end
+        end
+      end
     end
   end
 end

data/lib/super_diff/active_support/operation_tree_builders/hash_with_indifferent_access.rb

@@ -1,7 +1,7 @@
 module SuperDiff
   module ActiveSupport
     module OperationTreeBuilders
-      class HashWithIndifferentAccess < SuperDiff::OperationTreeBuilders::Hash
+      class HashWithIndifferentAccess < Basic::OperationTreeBuilders::Hash
         def self.applies_to?(expected, actual)
           (
             expected.is_a?(::HashWithIndifferentAccess) && actual.is_a?(::Hash)

data/lib/super_diff/active_support/operation_tree_flatteners/hash_with_indifferent_access.rb

@@ -1,7 +1,7 @@
 module SuperDiff
   module ActiveSupport
     module OperationTreeFlatteners
-      class HashWithIndifferentAccess < SuperDiff::OperationTreeFlatteners::Hash
+      class HashWithIndifferentAccess < Basic::OperationTreeFlatteners::Hash
         protected
 
         def open_token