treaty 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 72d96fdd6fd04921e3317e4cb6da530b650b59b7f3ea49df6f9a0eed48074c3c
-  data.tar.gz: 45838415475fbfabe6570fc29cea16d283edea99aa52f6c09ac1e37cc030c627
+  metadata.gz: d99db2724f9dd4fd84a7f315d1acf070dcf70a7f3669dab9980334dc2c179076
+  data.tar.gz: d02611a96da26130b8504818fabd9adbc10fa72b8984fc8330e7b63aec79c7ea
 SHA512:
-  metadata.gz: b26072eccaa4620c6e5797eb7fc549ba9b4765bb1f2cc56f6bc669cf2c84cc63533e6fb2a1588b89d629245964dc67d20d7031467551c6cfcce74a3149c0f098
-  data.tar.gz: 90f4a34188088c711d318b1c2a9696e18219a34c9def18b4230f02303b0ed54cda24818d1dbb49568dd6c8ff482c4e65b744a93c656fddeb8b7db97d70cc1a6e
+  metadata.gz: 492777e146c0042d9c78df8e9783a17d4aa705c629705425d7cd0db0ce2eaf5d8a2cf58b817c95fe1bc9025739044eb89959e91b04eb7e8dd205c6da9ab68251
+  data.tar.gz: 6133706b11654af81a88b32489d88d78f86a66df79a80a072c29fde23e2ea6130e0bee4ffe401def62f52a80ce293954228dd746bc57cf01d38e17833179f350

data/README.md

@@ -1,31 +1,32 @@
 # Treaty
 
-A gem to use pact-verifier via FFI in order to support the latest pact features.
+> [!WARNING]
+> This project is currently under development.
 
-Should be a replacement for `pact-ruby`, but most likely is very much incompatible
-due to large specification differences.
+## Quick Start
 
-:warning: This is just me hacking around with `ffi` and the pact verifier. Do not use this project.
-## Installation
+### Installation
 
-Install the gem and add to the application's Gemfile by executing:
+```ruby
+gem "treaty"
+```
 
-    $ bundle add treaty
+## Documentation
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+Complete documentation is available in the [docs](./docs) directory:
 
-    $ gem install treaty
-
-## Usage
-
-## Development
+- [Getting Started](./docs/getting-started.md) - installation and first steps
+- [Core Concepts](./docs/core-concepts.md) - fundamental concepts
+- [API Reference](./docs/api-reference.md) - complete API documentation
+- [Examples](./docs/examples.md) - practical examples
+- [Full Documentation Index](./docs/README.md) - all documentation topics
 
 ## Contributing
 
-## License
+This project is intended to be a safe, welcoming space for collaboration.
+Contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+We recommend reading the [contributing guide](./CONTRIBUTING.md) as well.
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
-
-## Code of Conduct
+## License
 
-Everyone interacting in the Treaty project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/treaty/blob/main/CODE_OF_CONDUCT.md).
+Treaty is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -5,6 +5,8 @@ require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
 
-require "standard/rake"
+require "rubocop/rake_task"
 
-task default: %i[spec standard]
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/treaty/attribute/base.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Attribute
+    # Base class for all attribute definitions in Treaty DSL.
+    #
+    # ## Purpose
+    #
+    # Represents a single attribute defined in request/response scopes.
+    # Handles:
+    # - Attribute metadata (name, type, nesting level)
+    # - Helper mode to simple mode conversion
+    # - Simple mode to advanced mode normalization
+    # - Nested attributes (for object and array types)
+    #
+    # ## Usage
+    #
+    # Attributes are created through DSL methods:
+    #   string :title, :required
+    #   integer :age, default: 18
+    #   object :author do
+    #     string :name
+    #   end
+    #
+    # ## Processing Flow
+    #
+    # 1. Extract helpers from arguments (`:required`, `:optional`)
+    # 2. Convert helpers to simple mode options
+    # 3. Merge with explicit options
+    # 4. Normalize all options to advanced mode
+    # 5. Apply defaults (required: true for request, false for response)
+    # 6. Process nested attributes if block given
+    #
+    # ## Nested Attributes
+    #
+    # Object and array types can have nested attributes:
+    # - `object` - nested attributes as direct children
+    # - `array` - nested attributes define array element structure
+    #
+    # Special scope `:_self` is used for simple arrays:
+    #   array :tags do
+    #     string :_self  # Array of strings
+    #   end
+    class Base
+      attr_reader :name,
+                  :type,
+                  :options,
+                  :nesting_level
+
+      # Creates a new attribute instance
+      #
+      # @param name [Symbol] The attribute name
+      # @param type [Symbol] The attribute type (:string, :integer, :object, :array, etc.)
+      # @param helpers [Array<Symbol>] Helper symbols (:required, :optional)
+      # @param nesting_level [Integer] Current nesting depth (default: 0)
+      # @param options [Hash] Attribute options (required, default, as, etc.)
+      # @param block [Proc] Block for defining nested attributes (for object/array types)
+      def initialize(name, type, *helpers, nesting_level: 0, **options, &block)
+        @name = name
+        @type = type
+        @nesting_level = nesting_level
+
+        validate_nesting_level!
+
+        # Separate helpers from non-helper symbols.
+        @helpers = extract_helpers(helpers)
+
+        # Merge helper options with explicit options.
+        merged_options = merge_options(@helpers, options)
+
+        # Normalize all options to advanced mode.
+        @options = OptionNormalizer.normalize(merged_options)
+
+        apply_defaults!
+
+        # Process nested attributes for object and array types.
+        process_nested_attributes(&block) if block_given?
+      end
+
+      # Returns collection of nested attributes for this attribute
+      #
+      # @return [Collection] Collection of nested attributes
+      def collection_of_attributes
+        @collection_of_attributes ||= Collection.new
+      end
+
+      # Checks if this attribute has nested attributes
+      #
+      # @return [Boolean] True if attribute is object/array with nested attributes
+      def nested?
+        object_or_array? && collection_of_attributes.exists?
+      end
+
+      # Checks if this attribute is an object or array type
+      #
+      # @return [Boolean] True if type is :object or :array
+      def object_or_array?
+        object? || array?
+      end
+
+      # Checks if this attribute is an object type
+      #
+      # @return [Boolean] True if type is :object
+      def object?
+        @type == :object
+      end
+
+      # Checks if this attribute is an array type
+      #
+      # @return [Boolean] True if type is :array
+      def array?
+        @type == :array
+      end
+
+      private
+
+      # Validates that nesting level doesn't exceed maximum allowed depth
+      #
+      # @raise [Treaty::Exceptions::NestedAttributes] If nesting exceeds limit
+      # @return [void]
+      def validate_nesting_level!
+        return unless @nesting_level > Treaty::Engine.config.treaty.attribute_nesting_level
+
+        # TODO: It is necessary to implement a translation system (I18n).
+        raise Treaty::Exceptions::NestedAttributes,
+              "Nesting level #{@nesting_level} exceeds maximum allowed level of " \
+              "#{Treaty::Engine.config.treaty.attribute_nesting_level}"
+      end
+
+      # Extracts helper symbols from arguments
+      #
+      # @param helpers [Array] Mixed array that may contain helper symbols
+      # @return [Array<Symbol>] Filtered array of valid helper symbols
+      def extract_helpers(helpers)
+        helpers.select do |helper|
+          helper.is_a?(Symbol) && HelperMapper.helper?(helper)
+        end
+      end
+
+      # Merges helper-derived options with explicit options
+      #
+      # @param helpers [Array<Symbol>] Helper symbols to convert
+      # @param explicit_options [Hash] Explicitly provided options
+      # @return [Hash] Merged options hash
+      def merge_options(helpers, explicit_options)
+        helper_options = HelperMapper.map(helpers)
+        helper_options.merge(explicit_options)
+      end
+
+      # Applies default values for options based on context (request/response)
+      # Must be implemented in subclasses
+      #
+      # @raise [NotImplementedError] If subclass doesn't implement
+      # @return [void]
+      def apply_defaults!
+        # Must be implemented in subclasses
+        raise NotImplementedError, "#{self.class} must implement #apply_defaults!"
+      end
+
+      # Processes nested attributes block for object/array types
+      # Must be implemented in subclasses
+      #
+      # @param block [Proc] Block containing nested attribute definitions
+      # @raise [NotImplementedError] If subclass doesn't implement
+      # @return [void]
+      def process_nested_attributes(&block)
+        # Must be implemented in subclasses
+        raise NotImplementedError, "#{self.class} must implement #process_nested_attributes"
+      end
+    end
+  end
+end

data/lib/treaty/attribute/builder/base.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Attribute
+    module Builder
+      # Base DSL builder for defining attributes in request/response scopes.
+      #
+      # ## Purpose
+      #
+      # Provides the DSL interface for defining attributes within scopes.
+      # Handles method_missing magic to support type-based method calls.
+      #
+      # ## Responsibilities
+      #
+      # 1. **DSL Interface** - Provides clean syntax for attribute definitions
+      # 2. **Method Dispatch** - Routes type methods (string, integer, etc.) to attribute creation
+      # 3. **Helper Support** - Handles helper symbols in various positions
+      # 4. **Nesting Tracking** - Tracks nesting level for nested attributes
+      #
+      # ## DSL Usage
+      #
+      # The builder enables this clean DSL syntax:
+      #
+      # ```ruby
+      # request do
+      #   scope :user do
+      #     string :name, :required
+      #     integer :age, default: 18
+      #     object :profile do
+      #       string :bio
+      #     end
+      #   end
+      # end
+      # ```
+      #
+      # ## Method Dispatch
+      #
+      # ### Type-based Methods
+      # When you call `string :name`, it routes through `method_missing`:
+      # 1. `string` becomes the type
+      # 2. `:name` becomes the attribute name
+      # 3. Calls `attribute(:name, :string, ...)`
+      #
+      # ### Helper Position Handling
+      # Handles helpers in different positions:
+      #
+      # ```ruby
+      # string :required, :name    # Helper first, then name
+      # string :name, :required    # Name first, then helper
+      # ```
+      #
+      # Both resolve to the same attribute definition.
+      #
+      # ## Nesting
+      #
+      # Tracks nesting level for:
+      # - Validation (enforcing maximum nesting depth)
+      # - Error messages (showing context)
+      #
+      # Maximum nesting level is configured in Treaty::Engine.config.
+      #
+      # ## Subclass Requirements
+      #
+      # Subclasses must implement:
+      # - `create_attribute` - Creates the appropriate attribute type (Request/Response)
+      #
+      # ## Architecture
+      #
+      # Used by:
+      # - Request::Builder - For request attribute definitions
+      # - Response::Builder - For response attribute definitions
+      class Base
+        attr_reader :nesting_level,
+                    :collection_of_attributes
+
+        # Creates a new builder instance
+        #
+        # @param collection_of_attributes [Collection] Collection to add attributes to
+        # @param nesting_level [Integer] Current nesting depth
+        def initialize(collection_of_attributes, nesting_level)
+          @collection_of_attributes = collection_of_attributes
+          @nesting_level = nesting_level
+        end
+
+        # Defines an attribute with explicit type
+        #
+        # @param name [Symbol] The attribute name
+        # @param type [Symbol] The attribute type
+        # @param helpers [Array<Symbol>] Helper symbols (:required, :optional)
+        # @param options [Hash] Attribute options
+        # @param block [Proc] Block for nested attributes
+        # @return [void]
+        def attribute(name, type, *helpers, **options, &block)
+          @collection_of_attributes << create_attribute(
+            name,
+            type,
+            *helpers,
+            nesting_level: @nesting_level,
+            **options,
+            &block
+          )
+        end
+
+        # Handles DSL methods like `string :name` where method name is the type
+        #
+        # @param type [Symbol] The attribute type (method name)
+        # @param name [Symbol] The attribute name (first argument)
+        # @param helpers [Array<Symbol>] Helper symbols
+        # @param options [Hash] Attribute options
+        # @param block [Proc] Block for nested attributes
+        # @return [void]
+        def method_missing(type, name, *helpers, **options, &block)
+          if name.is_a?(Symbol) && HelperMapper.helper?(name)
+            helpers.unshift(name)
+            name = helpers.shift
+          end
+
+          attribute(name, type, *helpers, **options, &block)
+        end
+
+        # Checks if method should be handled by method_missing
+        #
+        # @param name [Symbol] Method name
+        # @return [Boolean]
+        def respond_to_missing?(name, *)
+          super
+        end
+
+        private
+
+        # Creates an attribute instance (must be implemented in subclasses)
+        #
+        # @raise [NotImplementedError] If subclass doesn't implement
+        # @return [Attribute::Base] Created attribute instance
+        def create_attribute(*)
+          # Must be implemented in subclasses
+          raise NotImplementedError, "#{self.class} must implement #create_attribute"
+        end
+      end
+    end
+  end
+end

data/lib/treaty/attribute/collection.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+module Treaty
+  module Attribute
+    # Collection wrapper for sets of attributes.
+    #
+    # ## Purpose
+    #
+    # Provides a unified interface for working with collections of attributes.
+    # Uses Ruby Set internally for uniqueness but exposes Array-like interface.
+    #
+    # ## Usage
+    #
+    # Used internally by:
+    # - Scope factories (to store attributes in a scope)
+    # - Attribute::Base (to store nested attributes)
+    #
+    # ## Methods
+    #
+    # Delegates common collection methods to internal Set:
+    # - `<<` - Add attribute
+    # - `each`, `map`, `select`, `reject` - Iteration
+    # - `find`, `first` - Access
+    # - `size`, `empty?` - Size checks
+    # - `to_h` - Convert to hash
+    #
+    # Custom methods:
+    # - `exists?` - Returns true if collection is not empty
+    #
+    # ## Example
+    #
+    #   collection = Collection.new
+    #   collection << Attribute::Base.new(:name, :string)
+    #   collection << Attribute::Base.new(:age, :integer)
+    #   collection.size  # => 2
+    #   collection.exists?  # => true
+    class Collection
+      extend Forwardable
+
+      def_delegators :@collection,
+                     :<<,
+                     :to_h, :map,
+                     :each_with_object, :each,
+                     :select, :reject, :size,
+                     :find, :first,
+                     :empty?
+
+      # Creates a new collection instance
+      #
+      # @param collection [Set] Initial collection (default: empty Set)
+      def initialize(collection = Set.new)
+        @collection = collection
+      end
+
+      # Checks if collection has any elements
+      #
+      # @return [Boolean] True if collection is not empty
+      def exists?
+        !empty?
+      end
+    end
+  end
+end

data/lib/treaty/attribute/helper_mapper.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Attribute
+    # Maps DSL helper symbols to their simple mode option equivalents.
+    #
+    # ## Purpose
+    #
+    # Helpers provide the most concise syntax for common options.
+    # They are syntactic sugar that gets converted to simple mode options.
+    #
+    # ## Available Helpers
+    #
+    # - `:required` → `required: true`
+    # - `:optional` → `required: false`
+    #
+    # ## Usage Examples
+    #
+    # Helper mode (most concise):
+    #   string :title, :required
+    #   string :bio, :optional
+    #
+    # Equivalent to simple mode:
+    #   string :title, required: true
+    #   string :bio, required: false
+    #
+    # ## Processing Flow
+    #
+    # 1. Helper mode: `string :title, :required`
+    # 2. HelperMapper: `:required` → `required: true`
+    # 3. OptionNormalizer: `required: true` → `{ is: true, message: nil }`
+    # 4. Final: Advanced mode used internally
+    #
+    # ## Adding New Helpers
+    #
+    # To add a new helper:
+    # ```ruby
+    # HELPER_MAPPINGS = {
+    #   required: { required: true },
+    #   optional: { required: false },
+    #   my_helper: { my_option: :smth }  # New helper example
+    # }.freeze
+    # ```
+    class HelperMapper
+      HELPER_MAPPINGS = {
+        required: { required: true },
+        optional: { required: false }
+      }.freeze
+
+      class << self
+        # Maps helper symbols to their simple mode equivalents
+        #
+        # @param helpers [Array<Symbol>] Array of helper symbols
+        # @return [Hash] Simple mode options hash
+        def map(helpers)
+          helpers.each_with_object({}) do |helper, result|
+            mapping = HELPER_MAPPINGS.fetch(helper)
+            result.merge!(mapping) if mapping.present?
+          end
+        end
+
+        # Checks if a symbol is a registered helper
+        #
+        # @param symbol [Symbol] Symbol to check
+        # @return [Boolean] True if symbol is a helper
+        def helper?(symbol)
+          HELPER_MAPPINGS.key?(symbol)
+        end
+      end
+    end
+  end
+end

data/lib/treaty/attribute/option/base.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Attribute
+    module Option
+      # Base class for all option processors (validators and modifiers).
+      #
+      # ## Option Modes
+      #
+      # Treaty supports two modes for defining options:
+      #
+      # 1. **Simple Mode** - Concise syntax for common cases:
+      #    - `required: true`
+      #    - `as: :value`
+      #    - `default: 12`
+      #    - `in: %w[twitter linkedin]`
+      #
+      # 2. **Advanced Mode** - Extended syntax with custom messages:
+      #    - `required: { is: true, message: "Custom error" }`
+      #    - `as: { is: :value, message: nil }`
+      #    - `inclusion: { in: %w[...], message: "Must be one of..." }`
+      #
+      # ## Helpers
+      #
+      # Helpers are shortcuts in DSL that map to simple mode options:
+      # - `:required` → `required: true`
+      # - `:optional` → `required: false`
+      #
+      # ## Advanced Mode Keys
+      #
+      # Each option in advanced mode has a value key:
+      # - Default key: `:is` (used by most options)
+      # - Special key: `:in` (used by inclusion validator)
+      #
+      # The value key is defined by overriding `value_key` method in subclasses.
+      #
+      # ## Processing Phases
+      #
+      # Each option processor can participate in three phases:
+      # - Phase 1: Schema validation (validate DSL definition correctness)
+      # - Phase 2: Value validation (validate runtime data values)
+      # - Phase 3: Value transformation (transform values: defaults, renaming, etc.)
+      class Base
+        # Creates a new option processor instance
+        #
+        # @param attribute_name [Symbol] The name of the attribute
+        # @param attribute_type [Symbol] The type of the attribute
+        # @param option_schema [Object] The option schema (simple or advanced mode)
+        def initialize(attribute_name:, attribute_type:, option_schema:)
+          @attribute_name = attribute_name
+          @attribute_type = attribute_type
+          @option_schema = option_schema
+        end
+
+        # Phase 1: Validates schema (DSL definition)
+        # Override in subclasses if validation is needed
+        #
+        # @raise [Treaty::Exceptions::Validation] If schema is invalid
+        # @return [void]
+        def validate_schema!
+          # No-op by default
+        end
+
+        # Phase 2: Validates value (runtime data)
+        # Override in subclasses if validation is needed
+        #
+        # @param value [Object] The value to validate
+        # @raise [Treaty::Exceptions::Validation] If value is invalid
+        # @return [void]
+        def validate_value!(value)
+          # No-op by default
+        end
+
+        # Phase 3: Transforms value
+        # Returns transformed value or original if no transformation needed
+        # Override in subclasses if transformation is needed
+        #
+        # @param value [Object] The value to transform
+        # @return [Object] Transformed value
+        def transform_value(value)
+          value
+        end
+
+        # Indicates if this option processor transforms attribute names
+        # Override in subclasses if needed (e.g., AsModifier)
+        #
+        # @return [Boolean] True if this processor transforms names
+        def transforms_name?
+          false
+        end
+
+        # Returns the target name for the attribute if this processor transforms names
+        # Override in subclasses if needed (e.g., AsModifier)
+        #
+        # @return [Symbol] The target attribute name
+        def target_name
+          @attribute_name
+        end
+
+        protected
+
+        # Returns the value key for this option in advanced mode
+        # Default is :is, but can be overridden (e.g., :in for inclusion)
+        #
+        # @return [Symbol] The key used to store the value in advanced mode
+        def value_key
+          :is
+        end
+
+        # Checks if option is enabled
+        # Handles both simple mode (boolean) and advanced mode (hash with value key)
+        #
+        # @return [Boolean] Whether the option is enabled
+        def option_enabled?
+          return false if @option_schema.nil?
+          return @option_schema if @option_schema.is_a?(TrueClass) || @option_schema.is_a?(FalseClass)
+
+          @option_schema.fetch(value_key, false)
+        end
+
+        # Extracts the actual value from normalized schema
+        # Works with both simple mode and advanced mode
+        #
+        # In simple mode: returns the value directly
+        # In advanced mode: extracts value using the appropriate key (is/in)
+        #
+        # @return [Object] The actual value from the option schema
+        def option_value
+          return @option_schema unless @option_schema.is_a?(Hash)
+
+          @option_schema.fetch(value_key, nil)
+        end
+
+        # Gets custom error message from advanced mode schema
+        #
+        # @return [String, nil] Custom error message or nil for default message
+        def custom_message
+          return nil unless @option_schema.is_a?(Hash)
+
+          @option_schema.fetch(:message, nil)
+        end
+
+        # Checks if schema is in advanced mode
+        #
+        # @return [Boolean] True if schema is in advanced mode (hash with value key)
+        def advanced_mode?
+          @option_schema.is_a?(Hash) && @option_schema.key?(value_key)
+        end
+
+        # Checks if schema is in simple mode
+        #
+        # @return [Boolean] True if schema is in simple mode (not a hash or no value key)
+        def simple_mode?
+          !advanced_mode?
+        end
+      end
+    end
+  end
+end