specdiff 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7da7ac63f4638bd752f83ff41a27488757e43e57c028891d4fd944afd03f58ca
-  data.tar.gz: d5a49e6aeb3525a454df920aa7d1b541a0812ffb9f8d0e1813a4bc05b57b006f
+  metadata.gz: 8d698240eae3e0f8f38c22b66df23efb1076b14879a7093c3d3e33aebddd37c9
+  data.tar.gz: 29e6198145c5a9ede875a26066a33e599561fe82277c6eb8bdb475c291304c9b
 SHA512:
-  metadata.gz: 38ae83cd45a69892ca6d22915e0b253447eb12f42165a7673751abbb3993381702a02771ad3181a96d26204e6d171268a14423e85c2323a345df243be918f5a5
-  data.tar.gz: f44ce432951f3e2198ed6c4ed4cfc975b4eb201ced235791cd917c2476ca7a60fcb4ce0aff023fd4423f97b7eee2819d395d514b970188a5bc232ce89ee44ea6
+  metadata.gz: cb5b52f47732689bc8322b840436d4c27fb048dbe20e9e0d8501b3120137500b7a9230a9818c31e049aa22715c251166d807b4e01111695406470c6b314c13c5
+  data.tar.gz: 103362c058c1e260dc9a9c3f1bd06b06d39ab25c1818e001c7160eb61ceb741d549b4f9c6fb974bb27614456ab2d34dfae6732bc6d842d42346bd62abe1fc331

data/CHANGELOG.md

@@ -1,5 +1,24 @@
+# Changelog
+
+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] - 2023-12-04
+
+### Changed
+
+- Stop using thread locals ([#1](https://github.com/odinhb/specdiff/pull/1))
+
+## [0.1.1] - 2023-12-04
+
+### Fixed
+
+- Fix #empty? not returning true when the diff is actually empty
+
 ## [0.1.0] - 2023-11-30
 
 - Initial release

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    specdiff (0.1.0)
+    specdiff (0.2.0)
       diff-lcs (~> 1.5)
       hashdiff (~> 1.0)
 

data/README.md

@@ -47,8 +47,10 @@ Specdiff.configure do |config|
 end
 ```
 
-The webmock patch should make webmock show diffs from the specdiff gem when
-stubs mismatch.
+### WebMock
+
+The webmock patch should make webmock show request body diffs by using the
+specdiff gem when stubs mismatch. It only applies to request bodies.
 
 ### Direct usage
 
@@ -61,18 +63,68 @@ diff.empty? # => true/false, if it is empty you might want to not print the diff
 diff.to_s # => a string for showing to a developer who may or may not be scratching their head
 ```
 
+### Registering plugins
+
+```rb
+# Specdiff comes with json support, but it must be loaded like so:
+Specdiff.load!(:json)
+
+# Custom plugins can be loaded like this:
+Specdiff.load!(MyCustomType)
+```
+
+[Check out the source code](./lib/specdiff/plugins/json.rb) to learn the plugin interface.
+
 ## Development
 
+Check out the [glossary](./glossary.txt) to make sure you (and I) are using the
+same words for things ;)
+
 Install the software versions specified in `.tool-versions`.
 
 Run `bin/setup` to install dependencies. Then, run `bundle exec rake` to run the tests and linter and make sure they're green before starting to make your changes.
 
-Run `bundle exec rake -AD` gor a full list of all the available tasks you may use for development purposes.
+Run `bundle exec rake -AD` for a full list of all the available tasks you may use for development purposes.
 
 You can also run `bin/console` for an interactive prompt that will allow you to experiment with the gem code loaded.
 
+Remember to update the unreleased section of the [changelog](./CHANGELOG.md) before you submit your pull request.
+
+## How it works/"Architecture"
+
+High level description of the heuristic specdiff implements
+
+  1. receive 2 pieces of data: `a` and `b`
+  2. determine types for `a` and `b`
+      1. test against plugin types
+      2. test against built in types
+      3. fall back to the `:unknown` type
+  3. determine which differ is appropriate for the types
+      1. test against plugin differs
+      2. test against built in differs
+      3. fall back to the null differ (`NotFound`)
+  7. run the selected differ with a and b
+  8. package it into a `::Specdiff::Diff` which records the detected types
+
+  \<time passes>
+
+  6. at some point later when `#to_s` is invoked, stringify the diff using the differ's `#stringify`
+
 ## Releasing
 
+### Release procedure
+
+  - [ ] unit tests are passing (`$ bundle exec rake test`)
+  - [ ] linter is happy (`$ bundle exec rake lint`)
+  - [ ] `$ cd examples/webmock && bundle install && bundle exec ruby json.rb` looks good
+  - [ ] `$ bundle exec ruby text.rb` looks good
+  - [ ] update the version number in `version.rb`
+  - [ ] make sure the `examples/` `Gemfile.lock` files are updated
+  - [ ] move unreleased changes to the next version in the [changelog](./CHANGELOG.md)
+  - [ ] commit in the form "vX.X.X" and push
+  - [ ] make sure the pipeline is green
+  - [ ] `$ bundle exec rake release`
+
 To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
@@ -82,3 +134,12 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/odinhb
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## TODO
+
+This documents potential improvements/issues I know about or have thought about.
+
+- [ ] test the webmock monkey-patch. currently there is an empty webmock_spec.rb (should we do this using rspec?) and the examples/ directory contains a few webmock examples (which are a good idea to run before releasing) but it would be nice to have the pipeline fail if it doesn't work for whatever reason
+- [ ] finalize plugin interface (are the methods named intuitively? should we split type detector definitions and differ definitions?)
+- [ ] document how to define a plugin properly (instead of just linking to the source code)
+- [ ] is the stringification of hashdiff's output really better than pretty print? or just more wordy? (the colors are definitely nice)

data/examples/webmock/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ../..
   specs:
-    specdiff (0.1.0)
+    specdiff (0.2.0)
       diff-lcs (~> 1.5)
       hashdiff (~> 1.0)
 

data/glossary.txt

@@ -1,3 +1,8 @@
+"raw diff"
+  the return value from a differ or plugin's #diff method
+  this can be anything, from an array of arrays (hashdiff) to a string with a
+  git diff inside
+
 diff
   the return value from the Specdiff::diff method.
   this is not the direct return value from a plugin/differ, that is the
@@ -8,17 +13,34 @@ differ
   human-comprehensible diff output for your terminal
 
 plugin
-  external differ (responding to more methods), able to be provided by third
-  parties or end users themselves
+  external differ (has to respond to more methods)
+  may be provided from outside the gem (for example by a user drowning in xml)
+
+"built in differ"
+  differ living in the specdiff/differ directory
+
+"built in plugin"
+  plugin shipped with the gem, but needs to be loaded using Specdiff.load!
 
 type
   a symbol like :text, :json or :hash which denotes the type of data in a way
   which is useful for picking a differ
 
+  a plugin returns a type from its #id method
+
   :text
     a string which likely contains plaintext data of some kind
 
+"plugin type"
+  a type added by loading a plugin (not built into specdiff)
+
 side
-  an object containing either side of a comparison that needs to be made
-  when defining a plugin, the diff method receives two sides: a, b
-  most importantly, a side contains a value and a type
+  an object containing a value and a type
+
+  used to represent the two sides to a comparison
+
+  when defining a plugin, you receive two sides: a and b, to various methods
+
+compare
+  the procedure that implements the main function of specdiff including
+  accounting for any plugin types and differs

data/lib/specdiff/compare.rb

@@ -0,0 +1,95 @@
+class Specdiff::Compare
+  Side = Struct.new(:value, :type, keyword_init: true)
+
+  def self.call(...)
+    new.call(...)
+  end
+
+  def call(raw_a, raw_b)
+    a = parse_side(raw_a)
+    b = parse_side(raw_b)
+
+    if a.type == :text && b.type == :binary
+      new_b = try_reencode(b.value, a.value.encoding)
+      if new_b
+        b = b.dup
+        b.type = :text
+        b.value = new_b
+      end
+    elsif a.type == :binary && b.type == :text
+      new_a = try_reencode(a.value, b.value.encoding)
+      if new_a
+        a = a.dup
+        a.type = :text
+        a.value = new_a
+      end
+    end
+
+    differ = pick_differ(a, b)
+    raw = differ.diff(a, b)
+
+    if raw.is_a?(::Specdiff::Diff) # detect recursive plugins, such as json
+      raw
+    else
+      ::Specdiff::Diff.new(raw: raw, differ: differ, a: a, b: b)
+    end
+  end
+
+private
+
+  def parse_side(raw_value)
+    type = detect_type(raw_value)
+
+    Side.new(value: raw_value, type: type)
+  end
+
+  def detect_type(thing)
+    if (type = detect_plugin_types(thing))
+      type
+    elsif thing.is_a?(Hash)
+      :hash
+    elsif thing.is_a?(Array)
+      :array
+    elsif thing.is_a?(String) && thing.encoding == Encoding::BINARY
+      :binary
+    elsif thing.is_a?(String)
+      :text
+    elsif thing.nil?
+      :nil
+    else
+      :unknown
+    end
+  end
+
+  def detect_plugin_types(thing)
+    Specdiff.plugins
+      .filter { |plugin| plugin.respond_to?(:detect_type) }
+      .detect { |plugin| plugin.detect_type(thing) }
+      &.id
+  end
+
+  def try_reencode(binary_string, target_encoding)
+    binary_string.encode(target_encoding)
+  rescue StandardError
+    nil
+  end
+
+  def pick_differ(a, b)
+    if (differ = pick_plugin_differ(a, b))
+      differ
+    elsif a.type == :text && b.type == :text
+      Specdiff::Differ::Text
+    elsif a.type == :hash && b.type == :hash
+      Specdiff::Differ::Hashdiff
+    elsif a.type == :array && b.type == :array
+      Specdiff::Differ::Hashdiff
+    else
+      Specdiff::Differ::NotFound
+    end
+  end
+
+  def pick_plugin_differ(a, b)
+    Specdiff.plugins
+      .detect { |plugin| plugin.compatible?(a, b) }
+  end
+end

data/lib/specdiff/config.rb

@@ -5,23 +5,26 @@ module Specdiff
     end
   end
 
-  # Read the configuration
-  def self.config
-    threadlocal[:config] ||= default_configuration
+  class << self
+    attr_reader :config
   end
 
+  DEFAULT = Config.new(colorize: true).freeze
+  @config = DEFAULT.dup
+
   # private, used for testing
   def self._set_config(new_config)
-    threadlocal[:config] = new_config
+    @config = new_config
   end
 
   # Set the configuration
   def self.configure
-    yield(config)
+    yield(@config)
+    @config
   end
 
   # Generates the default configuration
   def self.default_configuration
-    Config.new(colorize: true)
+    DEFAULT
   end
 end

data/lib/specdiff/diff.rb

@@ -10,7 +10,8 @@
   end
 
   def empty?
-    differ == ::Specdiff::Differ::NotFound
+    differ == ::Specdiff::Differ::NotFound ||
+      (differ.respond_to?(:empty?) && differ.empty?(self))
   end
 
   def types

data/lib/specdiff/differ/hashdiff.rb

@@ -1,5 +1,4 @@
 require "hashdiff"
-require "pp"
 
 class Specdiff::Differ::Hashdiff
   extend ::Specdiff::Colorize
@@ -10,16 +9,18 @@ class Specdiff::Differ::Hashdiff
     # representation does not.
     # hmm it really seems like use_lcs: true gives much less human-readable
     # (human-comprehensible) output when arrays are involved.
-    Hashdiff.diff(
+    ::Hashdiff.diff(
       a.value, b.value,
       array_path: true,
       use_lcs: false,
     )
   end
 
-  def self.stringify(diff)
-    diff.raw.pretty_inspect
+  def self.empty?(diff)
+    diff.raw.empty?
+  end
 
+  def self.stringify(diff)
     result = +""
 
     diff.raw.each do |change|

data/lib/specdiff/differ/text.rb

@@ -47,6 +47,8 @@ class Specdiff::Differ::Text
       diff << hunks.last.diff(:unified).to_s
     end
 
+    return diff if diff == ""
+
     diff << "\n"
 
     return colorize_by_line(diff) do |line|
@@ -67,6 +69,10 @@ class Specdiff::Differ::Text
     end
   end
 
+  def self.empty?(diff)
+    diff.raw == ""
+  end
+
   def self.stringify(diff)
     diff.raw
   end

data/lib/specdiff/differ.rb

@@ -1,97 +1,4 @@
-class Specdiff::Differ
-  Side = Struct.new(:value, :type, keyword_init: true)
-
-  def self.call(...)
-    new.call(...)
-  end
-
-  def call(raw_a, raw_b)
-    a = parse_side(raw_a)
-    b = parse_side(raw_b)
-
-    if a.type == :text && b.type == :binary
-      new_b = try_reencode(b.value, a.value.encoding)
-      if new_b
-        b = b.dup
-        b.type = :text
-        b.value = new_b
-      end
-    elsif a.type == :binary && b.type == :text
-      new_a = try_reencode(a.value, b.value.encoding)
-      if new_a
-        a = a.dup
-        a.type = :text
-        a.value = new_a
-      end
-    end
-
-    differ = pick_differ(a, b)
-    raw = differ.diff(a, b)
-
-    if raw.is_a?(::Specdiff::Diff) # detect recursive plugins, such as json
-      raw
-    else
-      ::Specdiff::Diff.new(raw: raw, differ: differ, a: a, b: b)
-    end
-  end
-
-private
-
-  def parse_side(raw_value)
-    type = detect_type(raw_value)
-
-    Side.new(value: raw_value, type: type)
-  end
-
-  def detect_type(thing)
-    if (type = detect_plugin_types(thing))
-      type
-    elsif thing.is_a?(Hash)
-      :hash
-    elsif thing.is_a?(Array)
-      :array
-    elsif thing.is_a?(String) && thing.encoding == Encoding::BINARY
-      :binary
-    elsif thing.is_a?(String)
-      :text
-    elsif thing.nil?
-      :nil
-    else
-      :unknown
-    end
-  end
-
-  def detect_plugin_types(thing)
-    Specdiff.plugins
-      .filter { |plugin| plugin.respond_to?(:detect_type) }
-      .detect { |plugin| plugin.detect_type(thing) }
-      &.id
-  end
-
-  def try_reencode(binary_string, target_encoding)
-    binary_string.encode(target_encoding)
-  rescue StandardError
-    nil
-  end
-
-  def pick_differ(a, b)
-    if (differ = pick_plugin_differ(a, b))
-      differ
-    elsif a.type == :text && b.type == :text
-      Specdiff::Differ::Text
-    elsif a.type == :hash && b.type == :hash
-      Specdiff::Differ::Hashdiff
-    elsif a.type == :array && b.type == :array
-      Specdiff::Differ::Hashdiff
-    else
-      Specdiff::Differ::NotFound
-    end
-  end
-
-  def pick_plugin_differ(a, b)
-    Specdiff.plugins
-      .detect { |plugin| plugin.compatible?(a, b) }
-  end
+module Specdiff::Differ
 end
 
 # require only the builtin differs, plugins are optionally loaded later

data/lib/specdiff/plugins.rb

@@ -1,9 +1,8 @@
 module Specdiff
-  THREADLOCAL_PLUGINS_KEY = :__specdiff_plugins
-
-  def self.plugins
-    threadlocal[THREADLOCAL_PLUGINS_KEY]
+  class << self
+    attr_reader :plugins
   end
+  @plugins = []
 
   BUILTIN_PLUGINS = %i[json]
   BUILTIN_TYPES = %i[hash array binary text nil]
@@ -59,14 +58,13 @@ module Specdiff
       MSG
     end
 
-    ::Specdiff.plugins << plugin
+    @plugins << plugin
   end
 
   # private
   def self._clear_plugins!
-    threadlocal[THREADLOCAL_PLUGINS_KEY] = []
+    @plugins = []
   end
-  _clear_plugins!
 
   module Plugins
   end

data/lib/specdiff/version.rb

@@ -1,3 +1,3 @@
 module Specdiff
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/specdiff.rb

@@ -1,12 +1,12 @@
 require_relative "specdiff/version"
-require_relative "specdiff/threadlocal"
 require_relative "specdiff/config"
 require_relative "specdiff/colorize"
+require_relative "specdiff/compare"
 
 module Specdiff
   # Diff two things
   def self.diff(...)
-    ::Specdiff::Differ.call(...)
+    ::Specdiff::Compare.call(...)
   end
 end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: specdiff
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Odin Heggvold Bekkelund
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-11-30 00:00:00.000000000 Z
+date: 2023-12-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hashdiff
@@ -61,6 +61,7 @@ files:
 - glossary.txt
 - lib/specdiff.rb
 - lib/specdiff/colorize.rb
+- lib/specdiff/compare.rb
 - lib/specdiff/config.rb
 - lib/specdiff/diff.rb
 - lib/specdiff/differ.rb
@@ -70,7 +71,6 @@ files:
 - lib/specdiff/plugin.rb
 - lib/specdiff/plugins.rb
 - lib/specdiff/plugins/json.rb
-- lib/specdiff/threadlocal.rb
 - lib/specdiff/version.rb
 - lib/specdiff/webmock.rb
 - lib/specdiff/webmock/request_body_diff.rb

data/lib/specdiff/threadlocal.rb

@@ -1,8 +0,0 @@
-module Specdiff
-  THREADLOCAL_KEY = :__specdiff_threadlocals
-
-  def self.threadlocal
-    Thread.current.thread_variable_get(THREADLOCAL_KEY) ||
-      Thread.current.thread_variable_set(THREADLOCAL_KEY, {})
-  end
-end