katachi 0.0.0.1 → 0.0.1.0

data/lib/katachi/comparison_result.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+# A class to represent the result of a comparison.
+# It has a value, a shape, a code, and optionally child codes.
+# The code is a symbol that represents the result of the comparison.
+class Katachi::ComparisonResult
+  # CODES is a Hash of the form { code: boolean }.
+  # The boolean represents whether the code is considered a match or not.
+  # For example, :match is considered a match, while :mismatch is not.
+  CODES = {
+    # General
+    exact_match: true,
+    match: true,
+    mismatch: false,
+    class_mismatch: false,
+    # AnyOf
+    any_of_match: true,
+    any_of_mismatch: false,
+    # Array Overall
+    array_is_empty: true,
+    array_is_match: true,
+    array_is_mismatch: false,
+    array_is_exact_match: true,
+    array_class_matches_any_array: true,
+    # Array Elements
+    array_element_match: true,
+    array_element_mismatch: false,
+    # Hashes
+    hash_class_matches_any_hash: true,
+    hash_is_exact_match: true,
+    hash_is_mismatch: false,
+    hash_is_match: true,
+    # Hash[extra key checks]
+    hash_has_extra_keys: false,
+    hash_has_no_extra_keys: true,
+    # Hash[extra key checks][individual keys]
+    hash_key_exactly_allowed: true,
+    hash_key_match_allowed: true,
+    hash_key_not_allowed: false,
+    # Hash[missing key checks]
+    hash_has_missing_keys: false,
+    hash_has_no_missing_keys: true,
+    # Hash[missing key checks][individual keys]
+    hash_key_exact_match: true,
+    hash_key_match: true,
+    hash_key_missing: false,
+    hash_key_optional: true,
+    # Hash[value checks]
+    hash_values_are_mismatch: false,
+    hash_values_are_match: true,
+    # Hash[value checks][individual kv pairs] vs Shape
+    kv_match: true,
+    kv_mismatch: false,
+    kv_specific_match: true,
+    kv_specific_mismatch: false,
+    # Hash[value checks][individual kv pairs] vs Shape[individual kv pairs]
+    kv_key_mismatch: false,
+    kv_value_match: true,
+    kv_value_mismatch: false,
+  }.freeze
+
+  attr_reader :value, :shape, :code, :child_results
+
+  def initialize(value:, shape:, code:, child_results: nil)
+    raise ArgumentError, "code `#{code.inspect}` must be one of #{CODES.keys.inspect}" unless CODES.key?(code)
+
+    @value = value
+    @shape = shape
+    @code = code
+    @child_results = child_results
+    assert_child_codes_are_valid
+  end
+
+  def match? = CODES[code]
+
+  def to_s(child_label = nil) = [basic_text(child_label), *child_results_text_lines].compact.join("\n")
+
+  private
+
+  def basic_text(child_label)
+    child_label_affix = "; child_label: #{child_label.inspect}" if child_label
+    "#{code.inspect} <-- compare(value: #{value.inspect}, shape: #{shape.inspect})#{child_label_affix}"
+  end
+
+  def child_results_text_lines
+    child_results&.flat_map do |k, result|
+      result.to_s(k).split("\n").map { |line| "  #{line}" }
+    end
+  end
+
+  def assert_child_codes_are_valid
+    return unless child_results
+    raise ArgumentError, "child_results must be a Hash of ComparisonResult objects" unless child_results.is_a?(Hash)
+
+    return if child_results.values.all?(Katachi::ComparisonResult)
+
+    raise ArgumentError, "child_results must be a Hash of ComparisonResult objects"
+  end
+end

data/lib/katachi/predefined_shapes.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "shapes"
+
+Katachi::Shapes.add(:$uuid, /\A\h{8}-\h{4}-\h{4}-\h{4}-\h{12}\z/)

data/lib/katachi/rspec.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+RSpec::Matchers.define :have_shape do |expected|
+  diffable
+
+  match do |value|
+    if @expected_code
+      Kt.compare(value:, shape: expected).code == @expected_code
+    else
+      Kt.compare(value:, shape: expected).match?
+    end
+  end
+
+  chain :with_code do |expected_code|
+    @expected_code = expected_code
+  end
+end
+
+RSpec::Matchers.define :have_compare_code do |expected|
+  match { |value| value.code == expected }
+  diffable
+end

data/lib/katachi/shapes.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# A container for all the shapes
+module Katachi::Shapes
+  @shapes = {}
+  def self.valid_key?(key) = key.is_a?(Symbol) && key.to_s.start_with?("$")
+  def self.all = @shapes
+
+  def self.add(key, shape)
+    raise ArgumentError, "Invalid shape key: #{key}" unless valid_key?(key)
+
+    @shapes[key] = shape
+  end
+
+  def self.[](maybe_shape)
+    # :$undefined is a special case because it's a valid key but not a shape
+    # This is because it's used to represent a value that is not present in a hash
+    # Afaik it's the only shape that has to look at the parent of the value being compared
+    # instead of the value itself.
+    return maybe_shape if maybe_shape == :$undefined || !valid_key?(maybe_shape)
+
+    @shapes[maybe_shape] || raise(ArgumentError, "Unknown shape: #{maybe_shape}")
+  end
+end

data/lib/katachi/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Katachi
-  VERSION = "0.0.0.1"
+  VERSION = "0.0.1.0"
 end

data/lib/katachi.rb

@@ -1,8 +1,17 @@
 # frozen_string_literal: true
 
 require_relative "katachi/version"
+require_relative "katachi/comparison_result"
+require_relative "katachi/comparator"
+require_relative "katachi/any_of"
+require_relative "katachi/shapes"
+require_relative "katachi/predefined_shapes"
 
+# A tool for describing objects in a compact and readable way
 module Katachi
-  class Error < StandardError; end
-  # Your code goes here...
+  def self.compare(**) = Comparator.compare(**)
+  def self.any_of(*shapes) = AnyOf.new(*shapes)
+  def self.add_shape(key, shape) = Shapes.add(key, shape)
 end
+
+Kt = Katachi

data/renovate.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": [
+    "config:recommended"
+  ]
+}

metadata

@@ -1,21 +1,30 @@
 --- !ruby/object:Gem::Specification
 name: katachi
 version: !ruby/object:Gem::Version
-  version: 0.0.0.1
+  version: 0.0.1.0
 platform: ruby
 authors:
 - Joel Tannas
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-03-03 00:00:00.000000000 Z
+date: 2025-03-18 00:00:00.000000000 Z
 dependencies: []
 description: |
-  Experimenting with a new way of describing objects, particularly
-  in regards to APIs.
+  A tool for describing and validating objects as intuitively as possible.
 
-  Inspired by [RSwag](https://github.com/rswag/rswag) and the challenges
-  it faces with OpenAPI.
+  ```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(api_response.body).to have_shape(shape)
+  ```
 email:
 - jtannas@gmail.com
 executables: []
@@ -26,22 +35,36 @@ files:
 - ".rubocop.yml"
 - ".tool-versions"
 - CHANGELOG.md
-- CODE_OF_CONDUCT.md
+- Guardfile
 - LICENSE.txt
 - README.md
 - Rakefile
-- SECURITY.md
+- cspell.config.yaml
+- docs/CODE_OF_CONDUCT.md
+- docs/CONTRIBUTING.md
+- docs/HASH_COMPARISON_DESIGN.md
+- docs/PHILOSOPHY.md
+- docs/SECURITY.md
 - lib/katachi.rb
+- lib/katachi/any_of.rb
+- lib/katachi/comparator.rb
+- lib/katachi/comparator/compare_array.rb
+- lib/katachi/comparator/compare_hash.rb
+- lib/katachi/comparator/compare_kv.rb
+- lib/katachi/comparison_result.rb
+- lib/katachi/predefined_shapes.rb
+- lib/katachi/rspec.rb
+- lib/katachi/shapes.rb
 - lib/katachi/version.rb
-- sig/katachi.rbs
+- renovate.json
 homepage: https://github.com/jtannas/katachi
 licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/jtannas/katachi
   source_code_uri: https://github.com/jtannas/katachi
-  changelog_uri: https://github.com/jtannas/katachi/blob/main/CHANGELOG.md
-post_install_message:
+  changelog_uri: https://github.com/jtannas/katachi/releases
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -49,15 +72,17 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.2.0
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: '3.5'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.27
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
-summary: An RSpec plugin for describing and testing APIs
+summary: A tool for describing and validating objects as intuitively as possible.
 test_files: []

data/sig/katachi.rbs

@@ -1,4 +0,0 @@
-module Katachi
-  VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
-end