super_diff 0.11.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '08f4b984e0530c5c4ca5e1ba34b98b380a76712009a1b552a5e21106975293aa'
-  data.tar.gz: 12b49818665c952553c0b052e3fe8166de0c45a5eac7f9862c317560e0a06763
+  metadata.gz: 343438b938b014502f7af0df76fc22ff73f3eaada655081b994b8c4d77bd3618
+  data.tar.gz: 2738da41f517ecfcd1e068e03256cd37aa5436fd984856a2c958518596bd58bf
 SHA512:
-  metadata.gz: c6df90629d86a0c50680b10803cd1839ba0c94828627775fa840e1726fc70b57c6b13be7614ff35c00af960f3ea05530af6ba2d7dc7a3b9f9670fa8d17f75c72
-  data.tar.gz: 56015f9b40eb6f8b03be2c7b02dc641ea7493db0d7d4a8dae929753f7bf94d9a925f0678b8f68c1c2bf7eb705e2c019b3b38f7bfafb805379d8b37b9016f453d
+  metadata.gz: 522481e293667b16bf0d2c752fc02ebce5c6b8c607d23d53b009d52eec34e9a0d429fa410cb8dc4802c5b9b3dffd20632f9671024e3ba009e591179a6cb155dc
+  data.tar.gz: c08edc9460956e59f391249f26b508c944797ceda4db80d36b2119415322ef00210cd57817e74f24b6d13cc3b869bf7de1ca50276cd75e01288b1733c4c48b43

data/README.md

@@ -1,31 +1,28 @@
-# SuperDiff [![Gem Version][version-badge]][rubygems] [![Build Status][gh-actions-badge]][gh-actions] ![Downloads][downloads-badge] [![IssueHunt][issuehunt-badge]][issuehunt]
+# SuperDiff [![Gem Version][version-badge]][rubygems] [![Build Status][gh-actions-badge]][gh-actions] ![Downloads][downloads-badge]
 
 [version-badge]: http://img.shields.io/gem/v/super_diff.svg
 [rubygems]: http://rubygems.org/gems/super_diff
-[gh-actions-badge]: https://img.shields.io/github/actions/workflow/status/mcmire/super_diff/super_diff.yml?branch=master
+[gh-actions-badge]: https://img.shields.io/github/actions/workflow/status/splitwise/super_diff/super_diff.yml?branch=main
 [downloads-badge]: http://img.shields.io/gem/dtv/super_diff.svg
 [hound]: https://houndci.com
-[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 +30,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 +74,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 +83,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
 
@@ -252,20 +100,13 @@ and you encounter a bug or have a suggestion,
 feel free to [create an issue][issues-list].
 I'll try to respond to it as soon as I can!
 
-[issues-list]: https://github.com/mcmire/super_diff/issues
+[issues-list]: https://github.com/splitwise/super_diff/issues
 
 ## Contributing
 
 Any code contributions to improve this library are welcome!
-Please see the [contributing](./CONTRIBUTING.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).
-I'll get notified right away!
+Please see the [contributing](./docs/contributors/index.md) document
+for more on how to do that.
 
 ## Compatibility
 
@@ -274,7 +115,7 @@ Ruby >= 3.x,
 RSpec 3.x,
 and Rails >= 6.x.
 
-[gh-actions]: https://github.com/mcmire/super_diff/actions?query=workflow%3ASuperDiff
+[gh-actions]: https://github.com/splitwise/super_diff/actions?query=workflow%3ASuperDiff
 
 ## Inspiration/Thanks
 
@@ -289,13 +130,13 @@ I made use of or was heavily inspired by these libraries:
 
 Thank you to the authors of these libraries!
 
-[original-version]: https://github.com/mcmire/super_diff/tree/old-master
+[original-version]: https://github.com/splitwise/super_diff/tree/old-master
 [diff-lcs]: https://github.com/halostatue/diff-lcs
 [pretty-printer]: https://github.com/ruby/ruby/tree/master/lib/prettyprint.rb
 [awesome-print]: https://github.com/awesome-print/awesome_print
-[inspection-tree]: https://github.com/mcmire/super_diff/blob/master/lib/super_diff/object_inspection/inspection_tree.rb
+[inspection-tree]: https://github.com/splitwise/super_diff/blob/main/lib/super_diff/object_inspection/inspection_tree.rb
 
 ## Author/License
 
-SuperDiff was created and is maintained by Elliot Winkler.
+SuperDiff was created by Elliot Winkler and is maintained by Splitwise, Inc.
 It is released under the [MIT license](LICENSE).

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