katachi 0.0.0.1 → 0.0.1.1

data/docs/HASH_COMPARISON_DESIGN.md

@@ -0,0 +1,244 @@
+# Hash Comparison Design
+
+Katachi's hash comparison is inspired by OpenAPI (formerly Swagger) specs.
+
+Specifically, it's inspired by all the ways that I've repeatedly made
+goofy mistakes when writing them.
+
+Here's the story of how they led to the design of Katachi's hash comparison:
+
+## 3 Different Versions Of Nullable
+
+OpenAPI has handled `null` values a few different ways over the years.
+
+- OpenAPI 2.0 (Swagger) didn't support `null` values at all, so people used `x-nullable: true`
+- OpenAPI 3.0 make this official by supporting `nullable: true`
+- OpenAPI 3.1 found a much simpler way by treating `null` as a type: `type: ["string", "null"]`
+
+I like the 3.1 approach of treating `null` as just another possible type.
+I decided to take it further with Ruby's tools for inspecting types.
+We don't need the `type` description for fields -- Ruby can just tell us what type it is!
+
+We can just literally use `nil` as a possible value!
+
+All it takes is supporting a hash value being multiple types (e.g. `nil` or `String`).
+
+That led to the creation of `Katachi::AnyOf`.
+
+```ruby
+shape = { email: AnyOf[String, nil] }
+```
+
+## OpenAPI Keys Are Optional By Default
+
+> In the following description, if a field is not explicitly REQUIRED
+> or described with a MUST or SHALL, it can be considered OPTIONAL.
+>
+> \- [OpenAPI 3.1.1 Specification](https://spec.openapis.org/oas/v3.1.1)
+
+OpenAPI's decision to make all object keys optional by default has
+caught me multiple times.
+
+> "What do you mean the API response is empty?!? I tested it against the spec!"
+>
+> \- Me, multiple times
+
+I wanted to prevent people from falling into that trap, so Katachi has all the keys required by default. The comparison logic would be a simple set difference:
+
+```ruby
+    missing_keys = shape.keys - value.keys
+```
+
+## OpenAPI Extra Keys Are Allowed By Default
+
+> Additional properties are allowed by default in OpenAPI.
+> To enforce maximum strictness use additionalProperties: false to block all arbitrary data.
+>
+> \- [ApiMatic/OpenAPI/additionalProperties](https://www.apimatic.io/openapi/additionalproperties)
+
+On the flip side, OpenAPI's decision to allow extra keys in an object by default has also
+caught me multiple times.
+
+> "Why is the API response so big?!? It's nowhere near that bloated in the spec!"
+>
+> \- Me, multiple times
+
+Again, my chosen solution is to disallow extra keys by default.The comparison logic would be a simple set difference:
+
+```ruby
+    extra_keys = value.keys - shape.keys
+```
+
+... Right? (cue foreboding music)
+
+## Sane Defaults, But Inflexible
+
+With those decisions, the core design is starting to take shape:
+
+- All keys are required
+- No extra keys are allowed
+- `nil` is just another possible value; no special syntax needed
+
+That's a good set of defaults, but it's not flexible enough for most use cases.
+
+- Keys can be optional sometimes.
+- Extra keys can be allowed sometimes.
+- Sometimes you only want to test a few keys.
+
+I needed to add a way to make keys optional and a way to allow extra keys.
+
+## Allowing Optional Keys
+
+I wanted users to not have to look up a special syntax or use a proprietary class for when
+they want a hash key to be optional.
+
+Borrowing from OpenAPI 3.1's handling of `null`, I added a special value `:$undefined` to indicate that a key can be missing without the object being invalid.
+
+It's really convenient for users, but it comes with a new issue. We can no longer blindly assume that every key in the shape is required.
+
+```diff
+    missing_keys = shape.keys - value.keys
++   missing_keys -= optional_keys()
+```
+
+## Allowing Extra Keys
+
+Again, I wanted to make this easy for users without having to look up a special syntax. I eventually stumbled upon the idea of letting users add `Object => Object` to match any key-value pair.
+
+e.g. Checking just the email
+
+```ruby
+compare(
+    value: User.last.attributes,
+    shape: {
+        "email" => request.params[:email],
+        Object => Object,
+    },
+)
+```
+
+It looks a bit weird to have `Object` as a hash key, but it's perfectly valid Ruby.
+
+```diff
+    extra_keys = value.keys - shape.keys
++   extra_keys -= matching_keys()
+```
+
+## Matching Priority
+
+The problem with `Object => Object` is that it will match <ins>**literally any key-value pair**</ins>.
+
+That makes it impossible for the hash comparison to not find a valid match.
+
+So I had to put in a way for specific key matches (e.g. `email`) to take priority
+over more general matches. That led to a whole branch of code for checking for exact key matches
+between the shape and the value.
+
+## Non-Required Keys
+
+Another problem with using `Object => Object` for extra keys is that it's means that a key defined in the shape isn't necessarily required in the value.
+
+If the comparison threw a `:hash_mismatch` when the user's hash didn't literally have a key-value pair `Object => Object`, that'd ruin that whole feature.
+
+The lazy solution was to just ignore `Object => Object`, but what if users wanted to be a bit stricter about their extra keys?
+
+- `Symbol => String` is a normal data structure to enforce.
+- `:$email => User` is an excellent description for a lookup hash.
+
+We need to figure out a way to distinguish between shape keys that are required and which ones are more general matching rules.
+
+```diff
+    missing_keys = shape.keys - value.keys
+    missing_keys -= optional_keys()
++   missing_keys -= matcher_keys()
+```
+
+To keep things consistent, the solution ended up being to use the same `compare` algorithm on the hash keys as we do on any other value.
+
+## Diagnostic Labels
+
+All of these changes made the comparison logic much more complex than I had anticipated.
+What really brought it into a whole new level of complexity was the need to provide diagnostic labels for each comparison. Telling users "your hash isn't a match and we're not telling you why" is a frustrating user experience.
+
+It needs to report:
+
+- Which keys were missing
+- Which keys were extra
+- Which values didn't match
+
+That's too much information to stuff into a flat return value - it needs to be a nested structure where each comparison reports all the factors that led to the match or mismatch.
+
+## The Final Design
+
+That all combines to the general flow of hash comparison in Katachi:
+
+```yaml
+Definitions:
+    VHash: Value Hash
+    SHash: Shape Hash
+    VKey: Value Key
+    SKey: Shape Key
+    VValue: Value Value
+    SValue: Shape Value
+
+Katachi::Result: Did the VHash match the SHash?
+  missing_keys: Are all keys in the shape present in the value?
+    {each SKey comparisons}:
+        - Determine if the SKey is required or optional.
+            - Is the SKey a general matching rule?
+                - Yes: Consider it optional.
+                - No: It's a specific key. Does the corresponding SValue contain :$undefined?
+                    - Yes: SKey is optional.
+                    - No: SKey is required.
+        - Check if the SKey is present in the VHash.
+            - Identical: label as exact match.
+            - Match Any: label as match.
+            - Key Not required: label as optional.
+            - Else: label as missing key.
+  extra_keys: Are there any VKeys that aren't in the SHash?
+    {each VKey comparisons}:
+        - Is the VKey exactly in the SHash?
+            - Yes: label it as an exact match.
+            - No: Does it match any SKey matchers?
+                - Compare each SKey matcher to the VKey.
+                    - Yes: label that comparison as a general match.
+                    - No: label that comparison as a mismatch.
+                - Did any of them match?
+                    - Yes: label it as a match.
+                    - No: label it as an extra key.
+  values: Do the VValues match the corresponding SValues in the shape?
+    {each VKey comparisons}:
+        - Is the VKey exactly in the SHash?
+            - Yes: Compare the corresponding VValue to the SValue.
+                - Identical: label VValue as an exact match.
+                - Match: label VValue as a match.
+                - No Match: label VValue as a mismatch.
+            - No: Does the VKey match any SKey matching rules?
+                - Yes: Compare the corresponding VValue to the SValue.
+                    - Identical: label as exact match.
+                    - Match: label as match.
+                    - No Match: label as mismatch.
+                - No: label as mismatch.
+```
+
+## Conclusion
+
+Yeah...
+
+It was rough to code...
+
+But it makes for an awesome user experience :)
+
+```ruby
+shape = {
+    :$guid => {
+        email: :$email,
+        first_name: String,
+        last_name: String,
+        preferred_name: AnyOf[String, nil],
+        admin_only_information: AnyOf[Symbol => String, :$undefined],
+        Symbol => Object,
+    },
+}
+expect(value: api_response.body, shape:).to be_match
+```

data/docs/PHILOSOPHY.md

@@ -0,0 +1,43 @@
+# Philosophy
+
+> Every well-established project should have a philosophy that guides its development.
+> Without a core philosophy, development can languish in endless decision-making and have weaker APIs as a result.
+
+- [TanStack Form Philosophy](https://tanstack.com/form/latest/docs/philosophy)
+
+## Be Intuitive
+
+- When defining shapes for comparison, we want users to be able to guess the correct action.
+  > - "I want this to be a string" -> use `String`
+  > - "I want this text to look like "foo" -> use `/foo/`
+- If the user has to reference our docs more than once, we should aim for better.
+
+## Be Minimal
+
+- The smaller the public API, the faster users can pick it up and be productive.
+- Rely on existing Ruby (e.g. `===`, `in`, procs, etc...) so people can use the tool at the skill level they're comfortable with.
+
+## Be Predictable
+
+- Minimal state. At the time of writing this, the only mutable state in the entire project is the shape library.
+- No hidden side effects. Nothing should be altered unless the user explicitly asks for it.
+
+## Be Reliable
+
+- Extensively test all code to ensure it works as expected.
+- Use static analysis tools to catch bugs before they happen.
+- Use CI to ensure that the code works on all supported platforms.
+- Eliminate dependencies whenever possible so we're less vulnerable to outside influences.
+
+## Be Ruthless To Systems. Be Kind To People
+
+- ^ quote from Michael Brooks
+
+People -- whether users or contributors -- are going to make mistakes.
+We should be understanding and forgiving when they do.
+
+That being said, users suffer the consequences every time we let something slip. A small fix in our code saves each user from having to fix it themselves.
+We should be meticulous in our code to avoid giving users a bad experience.
+
+To that end, we lean heavily on automated dev tooling to keep everything on track.
+Linters, formatters, spellcheckers, scanners -- we'll use it all.

data/lib/katachi/any_of.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "comparison_result"
+require_relative "comparator"
+
+# AnyOf is used for allowing multiple shapes to be matched a single value.
+# If any of the shapes match the value, the value is considered a match.
+# If none of the shapes match the value, the value is considered a mismatch.
+# AnyOf is used in the following way:
+# Katachi::Comparator.compare(value, Katachi::AnyOf[shape1, shape2, shape3])
+class Katachi::AnyOf
+  include Enumerable
+
+  # AnyOf[shape1, shape2, shape3] is a shortcut for AnyOf.new(shape1, shape2, shape3)
+  def self.[](...) = new(...)
+  def initialize(*shapes) = (@shapes = shapes)
+
+  def each(&) = @shapes.each(&)
+
+  # AnyOf is considered a match if any of the shapes match the value
+  # If none of the shapes match the value, AnyOf is considered a mismatch
+  def kt_compare(value)
+    child_results = @shapes.to_h { |shape| [shape, Katachi::Comparator.compare(value:, shape:)] }
+    Katachi::ComparisonResult.new(
+      value:,
+      shape: @shapes,
+      code: child_results.values.any?(&:match?) ? :any_of_match : :any_of_mismatch,
+      child_results:,
+    )
+  end
+
+  # normally this `.inspect` redefinition would be for `.to_s` but Hash.to_s calls
+  # inspect on the keys and values, so we have to redefine inspect instead
+  # if we want a user-friendly string representation of complex objects
+  def inspect = "AnyOf[#{@shapes.map(&:inspect).join(", ")}]"
+end

data/lib/katachi/comparator/compare_array.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+# Katachi::Comparator.compare_array is the main entry point for comparing array.
+# It is called by Katachi::Comparator.compare and should not be called directly.
+# It returns a Katachi::ComparisonResult object.
+module Katachi::Comparator
+  # Compare a value that is an array against a shape
+  # This method is called by Katachi::Comparator.compare and should not be called directly.
+  # It is not private so that it can be tested directly.
+  #
+  # @param value [Array] the value to compare
+  # @param shape [Object] the shape to compare against
+  # @return [Katachi::ComparisonResult] the result of the comparison
+  def self.compare_array(value:, shape:)
+    failure = precompare_array(value:, shape:)
+    return failure if failure
+
+    child_results = compare_array_elements(array: value, shape:)
+    # All array elements must be valid against at least one sub_shape
+    is_match = child_results.values.all?(&:match?)
+    code = is_match ? :array_is_match : :array_is_mismatch
+    Katachi::ComparisonResult.new(value:, shape:, code:, child_results:)
+  end
+
+  # Check for early exit conditions that don't require iterating over the array
+  #
+  # @param value [Array] the value to compare
+  # @param shape [Object] the shape to compare against
+  # @return [Katachi::ComparisonResult, nil] the result of the comparison, or nil if no early exit condition is met
+  private_class_method def self.precompare_array(value:, shape:)
+    raise ArgumentError, "checked value must be an array" unless value.is_a?(Array)
+
+    early_exit_code = if shape == Array then :array_class_matches_any_array
+                      elsif !shape.is_a?(Array) then :class_mismatch
+                      elsif value == shape then :array_is_exact_match
+                      elsif value.empty? then :array_is_empty
+                      end
+    return unless early_exit_code
+
+    Katachi::ComparisonResult.new(value:, shape:, code: early_exit_code)
+  end
+
+  # Compare each element of the array against the shape
+  #
+  # @param array [Array] the array to compare
+  # @param shape [Object] the shape to compare against
+  # @return [Hash] a hash of the comparison results for each unique element
+  private_class_method def self.compare_array_elements(array:, shape:)
+    # Use uniq in this method so that
+    #   a) we're not doing redundant checks, and
+    #   b) the results are a readable length for large array with lots of overlap
+    array.uniq.to_h do |element|
+      element_checks = shape.to_h { |sub_shape| [sub_shape, compare(value: element, shape: sub_shape)] }
+      [
+        element,
+        Katachi::ComparisonResult.new(
+          value: element,
+          shape:,
+          code: element_checks.values.any?(&:match?) ? :array_element_match : :array_element_mismatch,
+          child_results: element_checks,
+        )
+      ]
+    end
+  end
+end

data/lib/katachi/comparator/compare_hash.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require_relative "compare_kv"
+
+# Katachi::Comparator.compare_hash is the main entry point for comparing hashes.
+# It is called by Katachi::Comparator.compare and should not be called directly.
+# It returns a Katachi::ComparisonResult object.
+#
+# WARNING: HERE BE DRAGONS
+# The methods in this section of the module are gnarly and heavily recursive.
+# For the story of why it was built this way, see `docs/HASH_COMPARISON_DESIGN.md`.
+module Katachi::Comparator
+  # Compare a value that is a hash against a shape
+  # This method is called by Katachi::Comparator.compare and should not be called directly.
+  # It is not private so that it can be tested directly.
+  #
+  # @param value [Hash] the value to compare
+  # @param shape [Object] the shape to compare against
+  # @return [Katachi::ComparisonResult] the result of the comparison
+  def self.compare_hash(value:, shape:)
+    failure = precompare_hash(value:, shape:)
+    return failure if failure
+
+    child_results = {
+      "$required_keys": compare_hash_required_keys(value_keys: value.keys, shape:),
+      "$extra_keys": compare_hash_extra_keys(value_keys: value.keys, shape_keys: shape.keys),
+      "$values": compare_hash_values(value:, shape:),
+    }
+    # All categories of checks must pass for the hash to be a match
+    code = child_results.values.all?(&:match?) ? :hash_is_match : :hash_is_mismatch
+    Katachi::ComparisonResult.new(value:, shape:, code:, child_results:)
+  end
+
+  # Check for early exit conditions that don't require iterating over the hash
+  #
+  # @param value [Hash] the value to compare
+  # @param shape [Object] the shape to compare against
+  # @return [Katachi::ComparisonResult, nil] the result of the comparison, or nil if no early exit condition is met
+  private_class_method def self.precompare_hash(value:, shape:)
+    raise ArgumentError, "checked value must be a hash" unless value.is_a?(Hash)
+
+    early_exit_code = if shape == Hash then :hash_class_matches_any_hash
+                      elsif !shape.is_a?(Hash) then :class_mismatch
+                      elsif value == shape then :hash_is_exact_match
+                      else
+                        return
+                      end
+
+    Katachi::ComparisonResult.new(value:, shape:, code: early_exit_code)
+  end
+
+  # Examines the keys of the shape to determine if any are required
+  # and then checks that the value has all required keys.
+  # It takes the full shape as an argument rather than just the keys
+  # because `:$undefined` in the `value` portion of a key-value pair
+  # affects whether a key is allowed to be omitted.
+  #
+  # @param value_keys [Array] the keys of the value
+  # @param shape [Hash] the shape to compare against
+  # @return [Katachi::ComparisonResult] the result of the comparison
+  private_class_method def self.compare_hash_required_keys(value_keys:, shape:)
+    checks = shape.keys.filter_map do |k|
+      check_key_requirement_status(value_keys:, shape:, shape_key: k) if required_key?(k)
+    end
+    Katachi::ComparisonResult.new(
+      value: value_keys,
+      shape:,
+      code: checks.all?(&:match?) ? :hash_has_no_missing_keys : :hash_has_missing_keys,
+      child_results: checks.to_h { |check| [check.shape, check] },
+    )
+  end
+
+  # Check if a key is present, optional, or missing
+  #
+  # @param value_keys [Array] the keys of the value
+  # @param shape [Hash] the shape to compare against
+  # @param shape_key [Object] the key from the shape to check the value_keys for
+  # @return [Katachi::ComparisonResult] the result of the comparison
+  private_class_method def self.check_key_requirement_status(value_keys:, shape:, shape_key:)
+    shared = {
+      shape: shape_key,
+      child_results: value_keys.to_h { |v_key| [v_key, compare(value: v_key, shape: shape_key)] },
+    }
+    if value_keys.include?(shape_key)
+      Katachi::ComparisonResult.new(value: shape_key, code: :hash_key_exact_match, **shared)
+    elsif shared[:child_results].values.any?(&:match?)
+      Katachi::ComparisonResult.new(value: value_keys, code: :hash_key_match, **shared)
+    elsif optional_key?(shape[shape_key])
+      Katachi::ComparisonResult.new(value: :$undefined, code: :hash_key_optional, **shared)
+    else
+      Katachi::ComparisonResult.new(value: :$undefined, code: :hash_key_missing, **shared)
+    end
+  end
+
+  # Determine if a key is required
+  # A key is not considered to be required if it implements a case
+  # equality operator (`===`) for loosely matching values.
+  # This is typically used for matching classes, ranges, regexes, etc.
+  # Arrays, hashes, and AnyOf are considered required if all of contents are required
+  #
+  # @param key [Object] a key in the shape that we want to know if it fits the criteria for being required
+  # @return [Boolean] true if the key is required, false
+  private_class_method def self.required_key?(key) # rubocop:disable Metrics/CyclomaticComplexity
+    case key
+    when Array, Katachi::AnyOf then key.all? { |k| required_key?(k) }
+    when Hash then key.all? { |(k, v)| required_key?(k) && required_key?(v) }
+    when ->(k) { Katachi::Shapes.valid_key?(k) } then required_key?(Katachi::Shapes[key])
+    when ->(k) { k.method(:===) != k.method(:==) } then false
+    else true
+    end
+  end
+
+  # Determine if a key is optional via the presence of the `$undefined` shape
+  # It uses `compare` instead of `.include?` because the shape may be a reference
+  # to a shape like `:$optional_string --> Katachi::AnyOf[String, :$undefined]`.
+  #
+  # @param shape_value [Object] the "value" portion of a key-value pair in the shape
+  # @return [Boolean] true if the key is optional, false otherwise
+  private_class_method def self.optional_key?(shape_value) = compare(value: :$undefined, shape: shape_value).match?
+
+  # Compare the keys of the value against the keys of the shape.
+  #
+  # @param value_keys [Array] the keys of the value
+  # @param shape_keys [Array] the keys of the shape
+  # @return [Katachi::ComparisonResult] the result of the comparison
+  private_class_method def self.compare_hash_extra_keys(value_keys:, shape_keys:)
+    checks = value_keys.map { |key| check_extra_key_status(shape_keys:, value_key: key) }
+    Katachi::ComparisonResult.new(
+      value: value_keys,
+      shape: shape_keys,
+      code: checks.all?(&:match?) ? :hash_has_no_extra_keys : :hash_has_extra_keys,
+      child_results: checks.to_h { |check| [check.value, check] },
+    )
+  end
+
+  # Check if a key is exactly equal (==) to a key in the shape
+  # or if it matches via our usual `compare` method.
+  #
+  # @param shape_keys [Array] the keys of the shape
+  # @param value_key [Object] the key to check if it matches any of the shape keys
+  # @return [Katachi::ComparisonResult] the result of the comparison
+  private_class_method def self.check_extra_key_status(shape_keys:, value_key:)
+    key_results = shape_keys.to_h { |s_key| [s_key, compare(value: value_key, shape: s_key)] }
+    code = if shape_keys.include?(value_key) then :hash_key_exactly_allowed
+           elsif key_results.values.any?(&:match?) then :hash_key_match_allowed
+           else
+             :hash_key_not_allowed
+           end
+    Katachi::ComparisonResult.new(value: value_key, shape: shape_keys, code:, child_results: key_results)
+  end
+
+  # Compare the values of the hash against the values of the shape.
+  # In the case where the exact same key is present in both the value and the shape,
+  # then it gets sent to be compared by `compare_specific_kv`.
+  # Otherwise, it gets sent to be compared by `compare_general_kv`.
+  # This is to support when users want to match a subset of the keys in a hash.
+  # e.g. `compare(value: User.last, shape: { email: request.params[:email], Symbol => Object })`
+  #
+  # @param value [Hash] the value to compare
+  # @param shape [Hash] the hash shape to compare against
+  # @return [Katachi::ComparisonResult] the result of the comparison
+  private_class_method def self.compare_hash_values(value:, shape:)
+    individual_checks = value.keys.to_h do |v_key|
+      value_kv = value.slice(v_key)
+      [value_kv, shape.key?(v_key) ? compare_specific_kv(value_kv:, shape:) : compare_general_kv(value_kv:, shape:)]
+    end
+    Katachi::ComparisonResult.new(
+      value:,
+      shape:,
+      code: individual_checks.values.all?(&:match?) ? :hash_values_are_match : :hash_values_are_mismatch,
+      child_results: individual_checks,
+    )
+  end
+end

data/lib/katachi/comparator/compare_kv.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# This section of the module contains the logic for comparing key-value pairs against shapes
+# It is called by Katachi::Comparator.compare_hash and cannot be called directly
+module Katachi::Comparator
+  # Compares a single key-value pair against a shape when the key exactly matches a shape key
+  # @param value_kv [Hash] A single key-value pair to compare
+  # @param shape [Hash] The shape to compare against
+  # @return [Katachi::ComparisonResult] The result of the comparison
+  private_class_method def self.compare_specific_kv(value_kv:, shape:)
+    key = value_kv.keys[0]
+    result = compare(value: value_kv[key], shape: shape[key])
+    Katachi::ComparisonResult.new(
+      value: value_kv,
+      shape: shape.slice(key),
+      code: result.match? ? :kv_specific_match : :kv_specific_mismatch,
+      child_results: { shape[key] => result },
+    )
+  end
+
+  # Compares a single key-value pair against a shape when the key does not exactly match a shape key
+  # @param value_kv [Hash] A single key-value pair to compare
+  # @param shape [Hash] The shape to compare against
+  # @return [Katachi::ComparisonResult] The result of the comparison
+  private_class_method def self.compare_general_kv(value_kv:, shape:)
+    value_kv_results = shape.keys.to_h do |s_key|
+      [shape.slice(s_key), compare_individual_kv(value_kv:, shape_kv: shape.slice(s_key))]
+    end
+    Katachi::ComparisonResult.new(
+      value: value_kv,
+      shape:,
+      code: value_kv_results.values.any?(&:match?) ? :kv_match : :kv_mismatch,
+      child_results: value_kv_results,
+    )
+  end
+
+  # Compares a single key-value pair against a single shape key-value pair
+  # @param value_kv [Hash] A single key-value pair to compare
+  # @param shape_kv [Hash] A single key-value pair from the shape to compare against
+  # @return [Katachi::ComparisonResult] The result of the comparison
+  private_class_method def self.compare_individual_kv(value_kv:, shape_kv:)
+    key_result = compare(value: value_kv.keys[0], shape: shape_kv.keys[0])
+    value_result = compare(value: value_kv.values[0], shape: shape_kv.values[0])
+    code = if !key_result.match? then :kv_key_mismatch
+           elsif !value_result.match? then :kv_value_mismatch
+           else
+             :kv_value_match
+           end
+    Katachi::ComparisonResult.new(
+      value: value_kv,
+      shape: shape_kv,
+      code:,
+      child_results: { "$kv_key": key_result, "$kv_value": value_result },
+    )
+  end
+end

data/lib/katachi/comparator.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "comparison_result"
+require_relative "comparator/compare_array"
+require_relative "comparator/compare_hash"
+
+# Checks a given value against a shape; returns a Katachi::Result
+module Katachi::Comparator
+  # The main method for comparing a value against a shape
+  # Most of the logic is delegated to the other methods within this module
+  # In order to handle nested arrays and hashes the comparison methods are
+  # often recursive.
+  #
+  # @param value [Object] The value to compare
+  # @param shape [Object] The shape to compare against
+  # @return [Katachi::ComparisonResult] The result of the comparison
+  def self.compare(value:, shape:)
+    retrieved_shape = Katachi::Shapes[shape]
+    return retrieved_shape.kt_compare(value) if retrieved_shape.respond_to?(:kt_compare)
+    return compare_equalities(value:, shape: retrieved_shape) if retrieved_shape.is_a?(Proc)
+
+    case value
+    when Array then compare_array(value:, shape: retrieved_shape)
+    when Hash then compare_hash(value:, shape: retrieved_shape)
+    else compare_equalities(value:, shape: retrieved_shape)
+    end
+  end
+
+  # The method for comparing two values that are not arrays or hashes
+  # It relies on the case equality operator (===) to do the heavy lifting.
+  #
+  # @param value [Object] The value to compare
+  # @param shape [Object] The shape to compare against
+  # @return [Katachi::ComparisonResult] The result of the comparison
+  def self.compare_equalities(value:, shape:)
+    code = if shape == value then :exact_match
+           elsif shape === value then :match # rubocop:disable Style/CaseEquality
+           else
+             :mismatch
+           end
+    Katachi::ComparisonResult.new(value:, shape:, code:)
+  end
+end