katachi 0.0.0.1 → 0.0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad0165ffcbc6b7a1e90e916df99564cf28dafdf658951145744a946612309fa4
-  data.tar.gz: 161a85a62de47928e8f4ac5c83b2dfdf583c077c43817c87c7e648b7ca4c3c33
+  metadata.gz: eae61d46a9a766e14abce3b55525a693129e315439ed4984312b081ebf188ec7
+  data.tar.gz: fddee880cf7f3aeb4911b47b5143242dd5f38e1fd0308498b1e745f032b71898
 SHA512:
-  metadata.gz: 45d3934a9606aaf37f90b4d3253f5c4ec6d9a8023bfd24db1307b71ed4781a7272c8e412f901015df1a6a0dcf8637b94e78dae5b53f75b4288b55dd9508353ac
-  data.tar.gz: a4fd2cc5b74d36a8da5e882afba202bc37ceec3a801ec190085b8e7912dfe84685b5b33d6ab18b7b484ff8f0c37e4a3a6a12f9154fdf1ed1174c8517c287cdb2
+  metadata.gz: 12e516977d0ad4fbb33b52920737b76bfc5fd218ce934fdd78691e16d38cd90ce62247fa89b6adc226bd0ae04cc6ece47c651c2ebd5c93e3fe0bef980fea2b9e
+  data.tar.gz: 76d6350536445901723c42df05b5cb2ed7bb15f781ee16896b03d88bc6cdae55a9e01bbf91a204776d820e4a3e9472eb7b0eaf5f88c34b3052ecdf7cd1fd25b1

data/.rubocop.yml

@@ -1,8 +1,42 @@
+plugins:
+  - rubocop-performance
+  - rubocop-rake
+  - rubocop-rspec
+
 AllCops:
-  TargetRubyVersion: 3.1
+  TargetRubyVersion: 3.2
+  NewCops: enable
+
+Layout/ClassStructure:
+  Enabled: true
+
+Metrics/MethodLength:
+  CountAsOne: &count_as_one
+    - array
+    - hash
+    - heredoc
+    - method_call
+
+RSpec/ExampleLength:
+  CountAsOne: *count_as_one
+
+Style/ClassAndModuleChildren:
+  EnforcedStyle: compact
+
+Style/EndlessMethod:
+  EnforcedStyle: require_single_line
+
+Style/HashSyntax:
+  EnforcedShorthandSyntax: always
 
 Style/StringLiterals:
   EnforcedStyle: double_quotes
 
 Style/StringLiteralsInInterpolation:
   EnforcedStyle: double_quotes
+
+Style/TrailingCommaInHashLiteral:
+  EnforcedStyleForMultiline: diff_comma
+
+Style/TrailingCommaInArguments:
+  EnforcedStyleForMultiline: consistent_comma

data/.tool-versions

@@ -1 +1 @@
-ruby 3.1.6 3.2.4 3.3.3
+ruby 3.2.7 3.3.7 3.4.2

data/Guardfile

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# More info at https://github.com/guard/guard#readme
+guard :rspec, cmd: "bundle exec rspec" do
+  require "guard/rspec/dsl"
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  # RSpec files
+  rspec = dsl.rspec
+  watch(rspec.spec_helper) { rspec.spec_dir }
+  watch(rspec.spec_support) { rspec.spec_dir }
+  watch(rspec.spec_files)
+
+  # Ruby files
+  ruby = dsl.ruby
+  dsl.watch_spec_files_for(ruby.lib_files)
+end

data/README.md

@@ -1,52 +1,320 @@
-# katachi
+![Gem Version](https://img.shields.io/gem/v/katachi)
 
-An RSpec plugin for testing APIs
+# Katachi
 
-TODO: Delete this and the text below, and describe your gem
+A tool for describing and validating objects as intuitively as possible.
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/katachi`. To experiment with that code, run `bin/console` for an interactive prompt.
+```ruby
+Katachi.compare(
+    value: {name: 'John', age: 30},
+    shape: {name: String, age: Integer}
+).match? # => true
+```
 
-## Installation
+## What's with the name?
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+> The word “katachi” is a composite of “kata” (pattern) and “chi” (magical power), thus it includes meanings such as “complete form” or “form telling an attractive story.” It can reveal the relationship between shape, function and meaning.
+>
+> https://symmetry-us.com/about_the_site/what-is-katachi/
 
-Install the gem and add to the application's Gemfile by executing:
+This tool is all about defining the shape of your data. The usual words of schema, definition, or validator all felt too formal. Since Ruby originated in Japan, I looked up the Japanese word for shape. It came back as 形 (katachi), and the above quote was the first thing I saw when checking for prior usage. It felt like a perfect fit.
 
-    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+## Features
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+### Basic Shape Matching
 
-    $ gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+A comparison system built on the power of the Ruby `===` operator.
 
-## Usage
+```ruby
+Kt = Katachi
+Kt.compare(value: 'hello', shape: 'hello').match? # => true
+Kt.compare(value: 'hello', shape: 'world').match? # => false
+Kt.compare(value: 'hello', shape: String).match? # => true
+Kt.compare(value: 'hello', shape: /ell/).match? # => true
+Kt.compare(value: 4, shape: 1..10).match? # => true
+Kt.compare(value: 4, shape: ->(v) { v > 3 }).match? # => true
+```
 
-TODO: Write usage instructions here
+If you're dealing with more variable data, there's`any_of` to allow multiple types.
+This is especially useful for optional values, since we treat `nil` just like any other value.
 
-## Development
+```ruby
+value = user.preferred_name
+shape = Kt.any_of(String, nil)
+Kt.compare(value:, shape:).match? # => true
+```
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+### An Easy-To-Use Shape Library
 
-To install this gem onto your local machine, run `bundle exec rake install`. 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).
+We provide some common shapes that can be accessed by `:${name}`.
 
-## Contributing
+```ruby
+Kt.compare(
+    value: "123e4567-e89b-12d3-a456-426614174000",
+    shape: :$uuid
+).match? # => true
+```
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/jtannas/katachi. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/jtannas/katachi/blob/main/CODE_OF_CONDUCT.md).
+You can also add your own shapes to fit your needs.
 
-## License
+```ruby
+Kt.add_shape(:$even, ->(v) { v.even? })
+Kt.compare(value: 4, shape: :$even).match? # => true
+```
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The full list of included shapes can be found in the [predefined_shapes.rb](./lib/katachi/predefined_shapes.rb) file.
+If you think there's a shape everyone should have, feel free to open an issue! Or better yet, a PR!
+
+### Array Comparison
+
+Arrays are checked to ensure their contents also match the shape.
+
+```ruby
+Kt.compare(value: [1], shape: [Integer]).match? # => true
+```
+
+Since arrays aren't usually a fixed length, we don't compare the length
+of the value and shape arrays. Instead, we treat the contents of the shape
+array like `any_of`.
+`[String, Integer]` is effectively shorthand for `[Kt.any_of(String, Integer)]`.
+
+```ruby
+# pseudo-code for how arrays are compared
+array_matches = value.all? do |element|
+  shape.any? do |shape_element|
+    Kt.compare(value: element, shape: shape_element).match?
+  end
+end
+```
+
+Seeing a few examples is probably the best way to understand how this works.
+
+```ruby
+Kt.compare(value: [1, 2, 3, 4, 5], shape: [Integer]).match? # => true
+Kt.compare(value: ['a', 'b', 'c'], shape: [Integer]).match? # => false
+Kt.compare(value: [1, 2, 'c'], shape: [Integer]).match? # => false
+Kt.compare(value: ['a', 2, 'c', 4], shape: [Integer, String]).match? # => true
+```
+
+We said arrays aren't _usually_ a fixed length but it does happen.
+
+For this situation, the Ruby `in` operator is your friend.
+
+Here's how you can check for an array of exactly 5 elements without a lot of typing.
+
+```ruby
+value = [1, 2, 3, 4, 5]
+shape = ->(v) { v in ([Integer] * 5) }
+Kt.compare(value:, shape:).match? # => true
+```
+
+It also works for when you want to check for specific values at specific indexes.
+
+```ruby
+value = [1, 'a', 2]
+shape = ->(v) { v in [Integer, String, Integer] }
+Kt.compare(value:, shape:).match? # => true
+```
+
+Checks are recursive, so you can nest arrays as deep as you like.
+
+```ruby
+value = [1, [2, [3, 4]]]
+shape = [Integer, [Integer, [Integer]]]
+Kt.compare(value:, shape:).match? # => true
+```
+
+### Hash Comparison
+
+Hashes are checked to ensure their keys and values match the shape.
+
+```ruby
+value = {a: 1}
+shape = {a: Integer}
+Kt.compare(value:, shape:).match? # => true
+```
+
+By default, no extra or missing hash keys are allowed.
+
+```ruby
+# This will fail because `:b` is not in the shape
+value = {a: 1, b: 2}
+shape = {a: Integer}
+Kt.compare(value:, shape:).match? # => false
+
+# This will fail because `:b` is missing from the value
+value = {a: 1}
+shape = {a: Integer, b: String}
+Kt.compare(value:, shape:).match? # => false
+```
+
+If you want to allow extra keys, no special syntax is needed.
+Ruby comes to the rescue!
+Ruby accepts more than just strings and symbols as hash keys.
+We take advantage of this by applying the same comparison logic to the keys as we do to the values.
+
+```ruby
+value = {a: 1, b: 2, c: 3}
+shape = {a: Integer, Symbol => Integer}
+Kt.compare(value:, shape:).match? # => true
+```
+
+This means you can use any shape you like for the keys, though it's usually best to stick to simple shapes.
+
+```ruby
+value = { "123e4567-e89b-12d3-a456-426614174000" => "My Id" }
+shape = { :$uuid => String}
+Kt.compare(value:, shape:).match? # => true
+```
+
+We've made sure that if you go through the trouble of describing an exact key, it will override more generic matches.
+We consider an exact key to be one that doesn't contain a Class, a Range, a Proc, or a Regexp.
+
+```ruby
+value = {a: 'a', b: 'b', c: 'c'}
+shape = {a: 'foo', Symbol => String}
+Kt.compare(value:, shape:).match? # => false
+```
+
+For making keys optional, we provide a special `:$undefined` shape.
+
+```ruby
+value = {a: 1}
+shape = {a: Integer, b: Kt.any_of(Integer, :$undefined)}
+Kt.compare(value:, shape:).match? # => true
+```
 
-## Code of Conduct
+As with arrays, hashes can be nested as deep as you like.
 
-Everyone interacting in the Katachi project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/jtannas/katachi/blob/main/CODE_OF_CONDUCT.md).
+```ruby
+value = {a: {b: {c: 1}}}
+shape = {a: {b: {c: Integer}}}
+Kt.compare(value:, shape:).match? # => true
+```
 
-## Versioning
+### Custom Comparisons
 
-This gem uses [Epoch Semantic Versioning](https://antfu.me/posts/epoch-semver).
+Need something more complex? Just add a `kt_compare` class method to whatever you'd like to compare.
+As long as it returns a `Katachi::Result`, you're good to go!
 
-The format is: `EPOCH.MAJOR.MINOR.PATCH`
+```ruby
+class CanRideThisRollerCoaster
+  def self.kt_compare(value:)
+    age_check = Kt.compare(value: value.age, shape: 14..)
+    height_check = Kt.compare(value: value.height, shape: 42..123)
+    has_parent_check = Kt.compare(value: value.has_parent, shape: true)
+    is_allowed = height_check.match? && (age_check.match? || has_parent_check.match?)
+    Kt::Result.new(
+      value:,
+      shape: self,
+      code: is_allowed ? :match : :mismatch,
+      child_results: {age_check:, height_check:, has_parent_check:}
+    )
+  end
+end
+```
 
-- EPOCH: Increment when you make significant or groundbreaking changes.
-- MAJOR: Increment when you make minor incompatible API changes.
-- MINOR: Increment when you add functionality in a backwards-compatible manner.
-- PATCH: Increment when you make backwards-compatible bug fixes.
+### RSpec Integration
+
+When using Rspec, the way it turns question mark methods in to `be_` methods is a perfect fit for our `match?` method.
+
+```ruby
+# The following two lines are equivalent
+expect(Kt.compare('abc', 'abc').match?).to be true
+expect(Kt.compare('abc', 'abc')).to be_match
+```
+
+For when you don't want a match, RSpec has a helpful utility for defining the opposite of a matcher.
+
+```ruby
+RSpec::Matchers.define_negated_matcher :be_mismatch, :be_match
+expect(Kt.compare('abc', 123)).to be_mismatch
+```
+
+We've also added RSpec matchers to make testing your shapes even easier.
+
+```ruby
+require 'katachi/rspec'
+
+expect(Kt.compare('abc', 123)).to have_compare_code(:mismatch)
+expect('abc').to have_shape(String)
+expect('abc').to have_shape('abc').with_code(:exact_match)
+```
+
+### Detailed Diagnostics
+
+All comparisons return a `Katachi::Result` object that contains detailed information about the comparison.
+
+```ruby
+value = {a: 1, foo: :bar}
+shape = { a: Integer, foo: String }
+result = Kt.compare(value:, shape:)
+result.match? # => false
+result.code # => :hash_is_mismatch
+result.child_results # contains the recursive results of interior comparisons
+result.to_s == <<~RESULT.chomp
+  :hash_is_mismatch <-- compare(value: {a: 1, foo: :bar}, shape: {a: Integer, foo: String})
+    :hash_has_no_missing_keys <-- compare(value: {a: 1, foo: :bar}, shape: {a: Integer, foo: String}); child_label: :$required_keys
+      :hash_key_exact_match <-- compare(value: :a, shape: :a); child_label: :a
+      :hash_key_exact_match <-- compare(value: :foo, shape: :foo); child_label: :foo
+    :hash_has_no_extra_keys <-- compare(value: {a: 1, foo: :bar}, shape: {a: Integer, foo: String}); child_label: :$extra_keys
+      :hash_key_exactly_allowed <-- compare(value: :a, shape: :a); child_label: :a
+      :hash_key_exactly_allowed <-- compare(value: :foo, shape: :foo); child_label: :foo
+    :hash_values_are_mismatch <-- compare(value: {a: 1, foo: :bar}, shape: {a: Integer, foo: String}); child_label: :$values
+      :kv_specific_match <-- compare(value: {a: 1}, shape: {a: Integer}); child_label: [:a, 1]
+        :match <-- compare(value: 1, shape: Integer); child_label: Integer
+      :kv_specific_mismatch <-- compare(value: {foo: :bar}, shape: {foo: String}); child_label: [:foo, :bar]
+        :mismatch <-- compare(value: :bar, shape: String); child_label: String
+RESULT
+```
+
+## Future Features Under Consideration
+
+- [ ] More shapes (e.g. `:$email`, `:$url`, `:$iso_8601`)
+- [ ] More "matching modifiers" (e.g. `all_of`, `one_of`, `none_of`)
+- [ ] Docusaurus github pages for documentation
+- [ ] More output formats (e.g. `to_json`, `to_hash`, etc...)
+- [ ] Custom shape codes (e.g. `:email_is_invalid`)
+- [ ] Minitest integration
+- [ ] Rails integration (e.g. `validates_shape_of`)
+- [ ] Shape-to-TypeScript conversion
+- [ ] Shape-to-Zod conversion
+- [ ] Shape-to-OpenAPI conversion
+- [ ] Recursive shape definitions (e.g. `:$user => {name: String, spouse: Kt.any_of(:$user, nil)}`)
+- [ ] `katachi-rspec-api` for testing+documenting APIs in a way inspired [RSwag](https://github.com/rswag/rswag)
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+$ bundle add katachi
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+$ gem install katachi
+```
+
+## Inspiration
+
+This is inspired by my experiences testing using [RSwag](https://github.com/rswag/rswag) and from my small part in helping maintain it. I wasn't happy with how often I had to look up the OpenAPI spec to be able to follow it.
+
+A lot of this came down to OpenAPI itself being complex and making significant changes over the years (e.g. `x-nullable: true` → `nullable: true` → `type: ["string", "null"]`). A bigger part is they're limited to valid JSON, so they have very few tools to work with.
+
+I started wondering if I could tweak RSwag to smooth over some of these rough edges. Is there a way to make it easier to write and harder to mess up?
+
+It started as consolidating a few helper functions together, before a bigger question hit me:
+
+**“What if I ditched writing OpenAPI entirely?”**
+
+Rather than drag all of their maintainers and users along with my crackpot schemes, I decided it was time to set off on a new project: `Katachi`
+
+## Development and Contributing
+
+See [CONTRIBUTING.md](./docs/CONTRIBUTING.md) for information on how to contribute to Katachi.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -10,3 +10,17 @@ require "rubocop/rake_task"
 RuboCop::RakeTask.new
 
 task default: %i[spec rubocop]
+
+desc "Opens a console with Katachi loaded for easier experimentation"
+task :console do
+  require "bundler/setup"
+  require "irb"
+  require "katachi"
+  ARGV.clear
+  IRB.start(__FILE__)
+end
+
+desc "All the steps necessary to get the project ready for development"
+task :setup do
+  system "bundle install"
+end

data/cspell.config.yaml

@@ -0,0 +1,19 @@
+$schema: https://raw.githubusercontent.com/streetsidesoftware/cspell/main/cspell.schema.json
+version: "0.2"
+words:
+  - bindir
+  - diffable
+  - kata
+  - Katachi
+  - kwargs
+  - PEBKAC
+  - pipefail
+  - popen
+  - precompare
+  - procs
+  - Rakefile
+  - readlines
+  - rubocop
+  - rubygems
+  - shapeables
+  - Tannas

data/docs/CONTRIBUTING.md

@@ -0,0 +1,35 @@
+# Contributing
+
+## Philosophy
+
+To guide development and explain "why was it done this way?" we have a [Philosophy](./PHILOSOPHY.md) document.
+Contributions should aim to follow the principles outlined there.
+
+## Development
+
+After checking out the repo, run `rake setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `rake console` for an interactive prompt that will allow you to experiment.
+
+In general, we want the `Rakefile` to be the source of truth for all tasks. If you find yourself manually running a task more than once, consider adding it to the `Rakefile`.
+
+We don't have a release process yet, but it's coming soon!
+
+## Contributing
+
+Bug reports and pull requests are welcome. Feature requests are welcome, but please open an issue first to discuss what you would like to change.
+
+Everyone interacting in the Katachi project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](./CODE_OF_CONDUCT.md).
+
+# Versioning
+
+This gem uses [Epoch Semantic Versioning](https://antfu.me/posts/epoch-semver).
+
+The format is: `EPOCH.MAJOR.MINOR.PATCH`
+
+> - EPOCH: Increment when you make significant or groundbreaking changes.
+> - MAJOR: Increment when you make minor incompatible API changes.
+> - MINOR: Increment when you add functionality in a backwards-compatible manner.
+> - PATCH: Increment when you make backwards-compatible bug fixes.
+
+Until we reach EPOCH 1, we will be in a state of rapid development.
+Breaking changes will still be communicated via major versions, but
+they may be fairly large in scope and number.