strict 0.0.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b23b160a9d38c3450223118fcf7c11f7833f1bd25c7f384c966e553e52430e52
-  data.tar.gz: 8588a01fe2783f8ad7955089af408d969e11713309e97db7eaaa38e344d8b070
+  metadata.gz: e55f68c10dc39769cdc9ae894efe2bbcd1a7ff0ce368b0b9b1d8251162cf1c6e
+  data.tar.gz: a3454e769c6cd9578c3a5fbe4abd6edd6b0518affcd69d89249235df874875f0
 SHA512:
-  metadata.gz: 284acd977a15b2d81a05d91b3dd2bfa3a0cfc9cad3e029cf2c10880020fbbbe23f6f7bfaf3b50d09b23ebc58e78cd65983ea156c7bc1cdd4bbd38337da6efcb6
-  data.tar.gz: f9c133d678e635b1d14dbb46acbcf71538aa9fc7508cfa3d75d47ae21015fef61f097956f6f3e89998b805e2ea16d4777f7c36802fc59e82783645b80525506c
+  metadata.gz: 06e647f606756054ece856881aff7de3b7c7fa50301c6b636af116b51ee8f975540b27bd6163391a18b8e8e40db911099e9dc7b1de7eacf38b239267b902287c
+  data.tar.gz: '09130d2f947390b821c9357c3c17a371236f14c864bb42c8165ef651fedb06943e0d6ad6021ae451549cd368e0546e2e15dfd5a12d3ed090c76091cbe178795f'

data/.rubocop.yml

@@ -1,9 +1,21 @@
+require:
+  - rubocop-minitest
+  - rubocop-rake
+
 AllCops:
   NewCops: enable
   TargetRubyVersion: 3.1.2
 
-Style/StringLiterals:
-  EnforcedStyle: double_quotes
+Style/CaseEquality:
+  Enabled: false
 
 Style/Documentation:
   Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Metrics/BlockLength:
+   Exclude:
+    - "test/**/*"
+    - "*.gemspec"

data/Gemfile.lock

@@ -1,22 +1,31 @@
 PATH
   remote: .
   specs:
-    strict (0.0.0)
+    strict (1.0.0)
       zeitwerk (~> 2.6)
 
 GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.2)
+    debug (1.6.1)
+      irb (>= 1.3.6)
+      reline (>= 0.3.1)
     gem-release (2.2.2)
+    io-console (0.5.11)
+    irb (1.4.1)
+      reline (>= 0.3.0)
     json (2.6.2)
     minitest (5.16.2)
+    minitest-spec-context (0.0.4)
     parallel (1.22.1)
     parser (3.1.2.1)
       ast (~> 2.4.1)
     rainbow (3.1.1)
     rake (13.0.6)
     regexp_parser (2.6.0)
+    reline (0.3.1)
+      io-console (~> 0.5)
     rexml (3.2.5)
     rubocop (1.36.0)
       json (~> 2.3)
@@ -30,6 +39,10 @@ GEM
       unicode-display_width (>= 1.4.0, < 3.0)
     rubocop-ast (1.21.0)
       parser (>= 3.1.1.0)
+    rubocop-minitest (0.22.2)
+      rubocop (>= 0.90, < 2.0)
+    rubocop-rake (0.6.0)
+      rubocop (~> 1.0)
     ruby-progressbar (1.11.0)
     unicode-display_width (2.3.0)
     zeitwerk (2.6.0)
@@ -39,10 +52,14 @@ PLATFORMS
   x86_64-linux
 
 DEPENDENCIES
+  debug (>= 1.0.0)
   gem-release (~> 2.2)
   minitest (~> 5.0)
+  minitest-spec-context (~> 0.0.4)
   rake (~> 13.0)
   rubocop (~> 1.21)
+  rubocop-minitest (~> 0.22)
+  rubocop-rake (~> 0.6)
   strict!
 
 BUNDLED WITH

data/README.md

@@ -1,22 +1,112 @@
 # Strict
 
-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/strict`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
+Strict provides a means to strictly validate instantiation of values, instantiation and attribute assignment of objects, and method calls at runtime.
 
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:
 
-    $ bundle add strict
+```sh
+$ bundle add strict
+```
 
 If bundler is not being used to manage dependencies, install the gem by executing:
 
-    $ gem install strict
+```sh
+$ gem install strict
+```
 
 ## Usage
 
-TODO: Write usage instructions here
+### `Strict::Value`
+
+```rb
+class Money
+  include Strict::Value
+
+  attributes do
+    amount_in_cents Integer
+    currency AnyOf("USD", "CAD"), default: "USD"
+  end
+end
+
+Money.new(amount_in_cents: 100_00)
+# => #<Money amount_in_cents=100_00 currency="USD">
+
+Money.new(amount_in_cents: 100_00, currency: "CAD")
+# => #<Money amount_in_cents=100_00 currency="CAD">
+
+Money.new(amount_in_cents: 100.00)
+# => Strict::InitializationError
+
+Money.new(amount_in_cents: 100_00).with(amount_in_cents: 200_00)
+# => #<Money amount_in_cents=200_00 currency="USD">
+
+Money.new(amount_in_cents: 100_00).amount_in_cents = 50_00
+# => NoMethodError
+
+Money.new(amount_in_cents: 100_00) == Money.new(amount_in_cents: 100_00)
+# => true
+```
+
+### `Strict::Object`
+
+```rb
+class Stateful
+  include Strict::Object
+
+  attributes do
+    some_state String
+    dependency Anything(), default: nil
+  end
+end
+
+Stateful.new(some_state: "123")
+# => #<Stateful some_state="123" dependency=nil>
+
+Stateful.new(some_state: "123").with(some_state: "456")
+# => NoMethodError
+
+Stateful.new(some_state: "123").some_state = "456"
+# => "456"
+# => #<Stateful some_state="456" dependency=nil>
+
+Stateful.new(some_state: "123").some_state = 456
+# => Strict::AssignmentError
+
+Stateful.new(some_state: "123") == Stateful.new(some_state: "123")
+# => false
+```
+
+### `Strict::Method`
+
+```rb
+class UpdateEmail
+  extend Strict::Method
+
+  sig do
+    user_id String, coerce: ->(value) { value.to_s }
+    email String
+    returns AnyOf(true, nil)
+  end
+  def call(user_id:, email:)
+    # contrived logic
+    user_id == email
+  end
+end
+
+UpdateEmail.new.call(user_id: 123, email: "123")
+# => true
+
+UpdateEmail.new.call(user_id: "123", email: "123")
+# => true
+
+UpdateEmail.new.call(user_id: "123", email: 123)
+# => Strict::MethodCallError
+
+UpdateEmail.new.call(user_id: "123", email: "456")
+# => Strict::MethodReturnError
+```
 
 ## Development
 
@@ -35,3 +125,7 @@ The gem is available as open source under the terms of the [MIT License](https:/
 ## Code of Conduct
 
 Everyone interacting in the Strict project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/kylekthompson/strict/blob/main/CODE_OF_CONDUCT.md).
+
+## Credit
+
+I can't thank [Tom Dalling](https://github.com/tomdalling) enough for his excellent [ValueSemantics](https://github.com/tomdalling/value_semantics) gem. Strict is heavily inspired and influenced by Tom's work and has some borrowed concepts and code.

data/lib/strict/accessor/attributes.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Strict
+  module Accessor
+    module Attributes
+      def attributes(&block)
+        block ||= -> {}
+        configuration = Strict::Attributes::Dsl.run(&block)
+        include Module.new(configuration)
+        include Strict::Attributes::Instance
+        extend Strict::Attributes::Configured
+      end
+    end
+  end
+end

data/lib/strict/accessor/module.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Strict
+  module Accessor
+    class Module < ::Module
+      attr_reader :configuration
+
+      # rubocop:disable Metrics/MethodLength
+      def initialize(configuration)
+        super()
+
+        @configuration = configuration
+        const_set(Strict::Attributes::Configured::CONSTANT, configuration)
+        configuration.attributes.each do |attribute|
+          module_eval(
+            "def #{attribute.name} = #{attribute.instance_variable}", # def name = @instance_variable
+            __FILE__,
+            __LINE__ - 2
+          )
+
+          module_eval(<<~RUBY, __FILE__, __LINE__ + 1)
+            def #{attribute.name}=(value)                                         # def name=(value)
+              attribute = self.class.strict_attributes.named!(:#{attribute.name}) #   attribute = self.class.strict_attributes.named!(:name)
+              value = attribute.coerce(value, for_class: self.class)              #   value = attribute.coerce(value, for_class: self.class)
+              if attribute.valid?(value)                                          #   if attribute.valid?(value)
+                #{attribute.instance_variable} = value                            #     @instance_variable = value
+              else                                                                #   else
+                raise Strict::AssignmentError.new(                                #     raise Strict::AssignmentError.new(
+                  assignable_class: self.class,                                   #       assignable_class: self.class,
+                  invalid_attribute: attribute,                                   #       invalid_attribute: attribute,
+                  value:                                                          #       value:
+                )                                                                 #     )
+              end                                                                 #   end
+            end                                                                   # end
+          RUBY
+        end
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      def inspect
+        "#<#{self.class} (#{configuration.attributes.map(&:name).join(', ')})>"
+      end
+    end
+  end
+end

data/lib/strict/assignment_error.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Strict
+  class AssignmentError < Error
+    attr_reader :invalid_attribute, :value
+
+    def initialize(assignable_class:, invalid_attribute:, value:)
+      super(message_from(assignable_class:, invalid_attribute:, value:))
+
+      @invalid_attribute = invalid_attribute
+      @value = value
+    end
+
+    private
+
+    def message_from(assignable_class:, invalid_attribute:, value:)
+      details = invalid_attribute_message_from(invalid_attribute, value)
+      "Assignment to #{invalid_attribute.name} of #{assignable_class} failed because:\n#{details}"
+    end
+
+    def invalid_attribute_message_from(invalid_attribute, value)
+      "  - got #{value.inspect}, expected #{invalid_attribute.validator.inspect}"
+    end
+  end
+end

data/lib/strict/attribute.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Strict
+  class Attribute
+    NOT_PROVIDED = ::Object.new.freeze
+
+    class << self
+      def make(name, validator = Validators::Anything.instance, coerce: false, **defaults)
+        unless valid_defaults?(**defaults)
+          raise ArgumentError, "Only one of 'default', 'default_value', or 'default_generator' can be provided"
+        end
+
+        new(name: name.to_sym, validator:, default_generator: make_default_generator(**defaults), coercer: coerce)
+      end
+
+      private
+
+      def valid_defaults?(default: NOT_PROVIDED, default_value: NOT_PROVIDED, default_generator: NOT_PROVIDED)
+        defaults_provided = [default, default_value, default_generator].count do |default_option|
+          !default_option.equal?(NOT_PROVIDED)
+        end
+
+        defaults_provided <= 1
+      end
+
+      def make_default_generator(default: NOT_PROVIDED, default_value: NOT_PROVIDED, default_generator: NOT_PROVIDED)
+        if !default.equal?(NOT_PROVIDED)
+          default.respond_to?(:call) ? default : -> { default }
+        elsif !default_value.equal?(NOT_PROVIDED)
+          -> { default_value }
+        elsif !default_generator.equal?(NOT_PROVIDED)
+          default_generator
+        else
+          NOT_PROVIDED
+        end
+      end
+    end
+
+    attr_reader :name, :validator, :default_generator, :coercer, :instance_variable
+
+    def initialize(name:, validator:, default_generator:, coercer:)
+      @name = name.to_sym
+      @validator = validator
+      @default_generator = default_generator
+      @coercer = coercer
+      @optional = !default_generator.equal?(NOT_PROVIDED)
+      @instance_variable = "@#{name.to_s.chomp('!').chomp('?')}"
+    end
+
+    def optional?
+      @optional
+    end
+
+    def valid?(value)
+      validator === value
+    end
+
+    def coerce(value, for_class:)
+      return value unless coercer
+
+      case coercer
+      when Symbol
+        for_class.public_send(coercer, value)
+      when true
+        for_class.public_send("coerce_#{name}", value)
+      else
+        coercer.call(value)
+      end
+    end
+  end
+end

data/lib/strict/attributes/configuration.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+module Strict
+  module Attributes
+    class Configuration
+      include Enumerable
+      extend Forwardable
+
+      class UnknownAttributeError < Error
+        attr_reader :attribute_name
+
+        def initialize(attribute_name:)
+          super(message_from(attribute_name:))
+
+          @attribute_name = attribute_name
+        end
+
+        private
+
+        def message_from(attribute_name:)
+          "Strict tried to find an attribute named #{attribute_name} but was unable. " \
+            "It's likely this in an internal bug, feel free to open an issue at #{Strict::ISSUE_TRACKER} for help."
+        end
+      end
+
+      def_delegator :attributes, :each
+
+      attr_reader :attributes
+
+      def initialize(attributes:)
+        @attributes = attributes
+        @attributes_index = attributes.to_h { |a| [a.name, a] }
+      end
+
+      def named!(name)
+        attributes_index.fetch(name) { raise UnknownAttributeError.new(attribute_name: name) }
+      end
+
+      private
+
+      attr_reader :attributes_index
+    end
+  end
+end

data/lib/strict/attributes/configured.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Strict
+  module Attributes
+    module Configured
+      CONSTANT = :STRICT_INTERNAL_ATTRIBUTES_CONFIGURATION__
+
+      def strict_attributes
+        self::STRICT_INTERNAL_ATTRIBUTES_CONFIGURATION__
+      end
+    end
+  end
+end

data/lib/strict/attributes/dsl.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Strict
+  module Attributes
+    class Dsl < BasicObject
+      class << self
+        def run(&)
+          dsl = new
+          dsl.instance_eval(&)
+          ::Strict::Attributes::Configuration.new(attributes: dsl.__strict_dsl_internal_attributes.values)
+        end
+      end
+
+      include ::Strict::Dsl::Validatable
+
+      attr_reader :__strict_dsl_internal_attributes
+
+      def initialize
+        @__strict_dsl_internal_attributes = {}
+      end
+
+      def strict_attribute(*args, **kwargs)
+        attribute = ::Strict::Attribute.make(*args, **kwargs)
+        __strict_dsl_internal_attributes[attribute.name] = attribute
+        nil
+      end
+
+      def method_missing(name, *args, **kwargs)
+        if respond_to_missing?(name)
+          strict_attribute(name, *args, **kwargs)
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(method_name, _include_private = nil)
+        first_letter = method_name.to_s.each_char.first
+        first_letter.eql?(first_letter.downcase)
+      end
+    end
+  end
+end

data/lib/strict/attributes/instance.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Strict
+  module Attributes
+    module Instance
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      def initialize(**attributes)
+        remaining_attributes = Set.new(attributes.keys)
+        invalid_attributes = nil
+        missing_attributes = nil
+
+        self.class.strict_attributes.each do |attribute|
+          if remaining_attributes.delete?(attribute.name)
+            value = attributes.fetch(attribute.name)
+          elsif attribute.optional?
+            value = attribute.default_generator.call
+          else
+            missing_attributes ||= []
+            missing_attributes << attribute.name
+            next
+          end
+
+          value = attribute.coerce(value, for_class: self.class)
+          if attribute.valid?(value)
+            instance_variable_set(attribute.instance_variable, value)
+          else
+            invalid_attributes ||= {}
+            invalid_attributes[attribute] = value
+          end
+        end
+
+        return if remaining_attributes.none? && invalid_attributes.nil? && missing_attributes.nil?
+
+        raise InitializationError.new(
+          initializable_class: self.class,
+          remaining_attributes:,
+          invalid_attributes:,
+          missing_attributes:
+        )
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+
+      def to_h
+        self.class.strict_attributes.to_h do |attribute|
+          [attribute.name, public_send(attribute.name)]
+        end
+      end
+
+      def inspect
+        if self.class.strict_attributes.any?
+          "#<#{self.class} #{to_h.map { |key, value| "#{key}=#{value.inspect}" }.join(' ')}>"
+        else
+          "#<#{self.class}>"
+        end
+      end
+
+      def pretty_print(pp)
+        pp.object_group(self) do
+          to_h.each do |key, value|
+            pp.breakable
+            pp.text("#{key}=")
+            pp.pp(value)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/strict/dsl/validatable.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Strict
+  module Dsl
+    module Validatable
+      # rubocop:disable Naming/MethodName
+
+      def AllOf(*subvalidators) = ::Strict::Validators::AllOf.new(*subvalidators)
+      def AnyOf(*subvalidators) = ::Strict::Validators::AnyOf.new(*subvalidators)
+      def Anything = ::Strict::Validators::Anything.instance
+      def ArrayOf(element_validator) = ::Strict::Validators::ArrayOf.new(element_validator)
+      def Boolean = ::Strict::Validators::Boolean.instance
+
+      def HashOf(key_validator_to_value_validator)
+        if key_validator_to_value_validator.size != 1
+          raise ArgumentError, "HashOf's usage is: HashOf(KeyValidator => ValueValidator)"
+        end
+
+        key_validator, value_validator = key_validator_to_value_validator.first
+        ::Strict::Validators::HashOf.new(key_validator, value_validator)
+      end
+
+      def RangeOf(element_validator) = ::Strict::Validators::RangeOf.new(element_validator)
+
+      # rubocop:enable Naming/MethodName
+    end
+  end
+end

data/lib/strict/initialization_error.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Strict
+  class InitializationError < Error
+    attr_reader :remaining_attributes, :invalid_attributes, :missing_attributes
+
+    def initialize(initializable_class:, remaining_attributes:, invalid_attributes:, missing_attributes:)
+      super(message_from(initializable_class:, remaining_attributes:, invalid_attributes:, missing_attributes:))
+
+      @remaining_attributes = remaining_attributes
+      @invalid_attributes = invalid_attributes
+      @missing_attributes = missing_attributes
+    end
+
+    private
+
+    def message_from(initializable_class:, remaining_attributes:, invalid_attributes:, missing_attributes:)
+      details = [
+        invalid_attributes_message_from(invalid_attributes),
+        missing_attributes_message_from(missing_attributes),
+        remaining_attributes_message_from(remaining_attributes)
+      ].compact.join("\n")
+
+      "Initialization of #{initializable_class} failed because:\n#{details}"
+    end
+
+    def invalid_attributes_message_from(invalid_attributes)
+      return nil unless invalid_attributes
+
+      details = invalid_attributes.map do |attribute, value|
+        "    - #{attribute.name}: got #{value.inspect}, expected #{attribute.validator.inspect}"
+      end.join("\n")
+
+      "  Some attributes were invalid:\n#{details}"
+    end
+
+    def missing_attributes_message_from(missing_attributes)
+      return nil unless missing_attributes
+
+      details = missing_attributes.map do |attribute_name|
+        "    - #{attribute_name}"
+      end.join("\n")
+
+      "  Some attributes were missing:\n#{details}"
+    end
+
+    def remaining_attributes_message_from(remaining_attributes)
+      return nil if remaining_attributes.none?
+
+      details = remaining_attributes.map do |attribute_name|
+        "    - #{attribute_name}"
+      end.join("\n")
+
+      "  Some attributes were provided, but not defined:\n#{details}"
+    end
+  end
+end

data/lib/strict/method.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Strict
+  module Method
+    def self.extended(mod)
+      return if mod.singleton_class?
+
+      mod.singleton_class.extend(self)
+    end
+
+    def sig(&)
+      instance = singleton_class? ? self : singleton_class
+      instance.instance_variable_set(:@__strict_method_internal_last_sig_configuration, Methods::Dsl.run(&))
+    end
+
+    # rubocop:disable Metrics/MethodLength
+    def singleton_method_added(method_name)
+      super
+
+      sig = singleton_class.instance_variable_get(:@__strict_method_internal_last_sig_configuration)
+      singleton_class.instance_variable_set(:@__strict_method_internal_last_sig_configuration, nil)
+      return unless sig
+
+      verifiable_method = Methods::VerifiableMethod.new(
+        method: singleton_class.instance_method(method_name),
+        parameters: sig.parameters,
+        returns: sig.returns,
+        instance: false
+      )
+      verifiable_method.verify_definition!
+      singleton_class.prepend(Methods::Module.new(verifiable_method))
+    end
+
+    def method_added(method_name)
+      super
+
+      sig = singleton_class.instance_variable_get(:@__strict_method_internal_last_sig_configuration)
+      singleton_class.instance_variable_set(:@__strict_method_internal_last_sig_configuration, nil)
+      return unless sig
+
+      verifiable_method = Methods::VerifiableMethod.new(
+        method: instance_method(method_name),
+        parameters: sig.parameters,
+        returns: sig.returns,
+        instance: true
+      )
+      verifiable_method.verify_definition!
+      prepend(Methods::Module.new(verifiable_method))
+    end
+    # rubocop:enable Metrics/MethodLength
+  end
+end