treaty 0.0.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 72d96fdd6fd04921e3317e4cb6da530b650b59b7f3ea49df6f9a0eed48074c3c
-  data.tar.gz: 45838415475fbfabe6570fc29cea16d283edea99aa52f6c09ac1e37cc030c627
+  metadata.gz: 2697d0627eb77c0671a3b71a5aacefc47acd90339214badcc68ab30ad61b96b0
+  data.tar.gz: 32dfce4473730165c99715bbc83d2c822148fb6392bc47a098bcd7771131b748
 SHA512:
-  metadata.gz: b26072eccaa4620c6e5797eb7fc549ba9b4765bb1f2cc56f6bc669cf2c84cc63533e6fb2a1588b89d629245964dc67d20d7031467551c6cfcce74a3149c0f098
-  data.tar.gz: 90f4a34188088c711d318b1c2a9696e18219a34c9def18b4230f02303b0ed54cda24818d1dbb49568dd6c8ff482c4e65b744a93c656fddeb8b7db97d70cc1a6e
+  metadata.gz: b6681d643573b27f56102619b50ef8f48e332b834e580f4d0dc164f0c5e298f221da2877db78d2c88853857f682b5f183b58c86e0b2d72c540a7462670d150d7
+  data.tar.gz: 70f69a8794ff010e115fdb80c81fc954ed1bd2881509cbcbf9d714957714c298775291e03f2268633d4fc8e293820a3a3cdd93cc2cb249b3beb51ffd64029037

data/README.md

@@ -1,31 +1,120 @@
-# Treaty
+<div align="center">
+  <h1>Treaty</h1>
+  <p>A Ruby library for defining and managing REST API contracts with versioning support.</p>
+</div>
 
-A gem to use pact-verifier via FFI in order to support the latest pact features.
+<div align="center">
 
-Should be a replacement for `pact-ruby`, but most likely is very much incompatible
-due to large specification differences.
+[![Gem Version](https://img.shields.io/gem/v/treaty.svg)](https://rubygems.org/gems/treaty)
+[![Release Date](https://img.shields.io/github/release-date/servactory/treaty)](https://github.com/servactory/servactory/releases)
+[![Gem Downloads](https://img.shields.io/gem/dt/treaty.svg)](https://rubygems.org/gems/treaty)
+![Ruby Version](https://img.shields.io/badge/Ruby-3.2%2B-red)
 
-:warning: This is just me hacking around with `ffi` and the pact verifier. Do not use this project.
-## Installation
+</div>
 
-Install the gem and add to the application's Gemfile by executing:
+## 📚 Documentation
 
-    $ bundle add treaty
+Explore comprehensive guides and documentation at [docs](./docs):
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+- [Getting Started](./docs/getting-started.md) - installation and configuration
+- [Core Concepts](./docs/core-concepts.md) - understand fundamental concepts
+- [API Reference](./docs/api-reference.md) - complete API documentation
+- [Examples](./docs/examples.md) - practical real-world examples
+- [Internationalization](./docs/internationalization.md) - I18n and multilingual support
+- [Full Documentation Index](./docs/README.md) - all documentation topics
 
-    $ gem install treaty
+## 💡 Why Treaty?
 
-## Usage
+Treaty provides a complete solution for building versioned APIs in Ruby on Rails:
 
-## Development
+- **Type Safety** - Enforce strict type checking for request and response data
+- **API Versioning** - Manage multiple concurrent API versions effortlessly
+- **Built-in Validation** - Validate incoming requests and outgoing responses automatically
+- **Data Transformation** - Transform data seamlessly between different API versions
+- **Deprecation Management** - Mark versions as deprecated with flexible conditions
+- **Internationalization** - Full I18n support for multilingual error messages
+- **Well-documented** - Comprehensive guides and examples for every feature
 
-## Contributing
+## 🚀 Quick Start
 
-## License
+### Installation
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+Add Treaty to your Gemfile:
 
-## Code of Conduct
+```ruby
+gem "treaty"
+```
 
-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).
+Run:
+
+```bash
+bundle install
+```
+
+### Define Treaty
+
+Create your first API contract in `app/treaties/posts/create_treaty.rb`:
+
+```ruby
+module Posts
+  class CreateTreaty < ApplicationTreaty
+    version 1, default: true do
+      strategy Treaty::Strategy::ADAPTER
+
+      request do
+        scope :post do
+          string :title, :required
+          string :content, :required
+          string :summary, :optional
+        end
+      end
+
+      response 201 do
+        scope :post do
+          string :id
+          string :title
+          string :content
+          string :summary
+          datetime :created_at
+        end
+      end
+
+      delegate_to Posts::CreateService
+    end
+  end
+end
+```
+
+### Use in Controller
+
+Define the treaty in your controller `app/controllers/posts_controller.rb`:
+
+```ruby
+class PostsController < ApplicationController
+  # Treaty automatically:
+  # 1. Validates incoming parameters according to request definition
+  # 2. Calls Posts::CreateService with validated data
+  # 3. Validates service response according to response definition
+  # 4. Returns transformed data to client
+  treaty :create
+end
+```
+
+## 🤝 Contributing
+
+We welcome contributions! You can help by:
+
+- Reporting bugs and suggesting features
+- Writing code and improving documentation
+- Reviewing pull requests
+- Sharing your experience with Treaty
+
+Please read our [Contributing Guide](./CONTRIBUTING.md) before submitting a pull request.
+
+## 🙏 Acknowledgments
+
+Thank you to all [contributors](https://github.com/servactory/treaty/graphs/contributors) who have helped make Treaty better!
+
+## 📄 License
+
+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/config/locales/en.yml

@@ -0,0 +1,96 @@
+en:
+  treaty:
+    # ============================================================================
+    # Attributes: Definition, validation, and processing
+    # ============================================================================
+    attributes:
+      # Attribute value validators
+      validators:
+        required:
+          blank: "Attribute '%{attribute}' is required but was not provided or is empty"
+
+        type:
+          unknown_type: "Unknown type '%{type}' for attribute '%{attribute}'. Allowed types: %{allowed}"
+          mismatch:
+            integer: "Attribute '%{attribute}' must be an Integer, got %{actual}"
+            string: "Attribute '%{attribute}' must be a String, got %{actual}"
+            object: "Attribute '%{attribute}' must be a Hash (object), got %{actual}"
+            array: "Attribute '%{attribute}' must be an Array, got %{actual}"
+            datetime: "Attribute '%{attribute}' must be a DateTime/Time/Date, got %{actual}"
+
+        inclusion:
+          invalid_schema: "Option 'inclusion' for attribute '%{attribute}' must have a non-empty array of allowed values"
+          not_included: "Attribute '%{attribute}' must be one of: %{allowed}. Got: '%{value}'"
+
+        # Nested structures validation
+        nested:
+          # Orchestrator errors
+          orchestrator:
+            collection_not_implemented: "Subclass must implement the collection_of_scopes method"
+            scope_data_not_implemented: "Subclass must implement the scope_data_for method"
+
+          # Array validation errors
+          array:
+            element_validation_error: "Error in array '%{attribute}' at index %{index}: Element must match one of the defined types. Errors: %{errors}"
+            element_type_error: "Error in array '%{attribute}' at index %{index}: Expected Hash but got %{actual}"
+            attribute_error: "Error in array '%{attribute}' at index %{index}: %{message}"
+
+      # Attribute options
+      options:
+        unknown: "Unknown options for attribute '%{attribute}': %{unknown}. Known options: %{known}"
+
+      # Attribute modifiers
+      modifiers:
+        as:
+          invalid_type: "Option 'as' for attribute '%{attribute}' must be a Symbol. Got: %{type}"
+
+      # Attribute builder DSL
+      builder:
+        not_implemented: "%{class} must implement #create_attribute"
+
+      # Attribute-level errors
+      errors:
+        nesting_level_exceeded: "Nesting level %{level} exceeds maximum allowed level of %{max_level}"
+        apply_defaults_not_implemented: "%{class} must implement #apply_defaults!"
+        process_nested_not_implemented: "%{class} must implement #process_nested_attributes"
+
+    # ============================================================================
+    # Versioning: API version management and resolution
+    # ============================================================================
+    versioning:
+      # Version resolver
+      resolver:
+        current_version_required: "Current version is required for validation"
+        version_not_found: "Version %{version} not found in treaty definition"
+        version_deprecated: "Version %{version} is deprecated and cannot be used"
+
+      # Version factory
+      factory:
+        invalid_default_option: "Default option for version must be true, false, or a Proc, got: %{type}"
+        unknown_method: "Unknown method: %{method}"
+
+      # Strategy validation
+      strategy:
+        unknown: "Unknown strategy: %{strategy}"
+
+    # ============================================================================
+    # Execution: Service and executor invocation
+    # ============================================================================
+    execution:
+      executor_missing: "Executor is not defined for version %{version}"
+      executor_empty: "Executor cannot be an empty string"
+      executor_not_found: "Executor class `%{class_name}` not found"
+      executor_invalid_type: "Invalid executor type: %{type}. Expected Proc, Class, String, or Symbol"
+      method_not_found: "Method '%{method}' not found in class '%{class_name}'"
+      proc_error: "%{message}"
+      servactory_input_error: "%{message}"
+      servactory_internal_error: "%{message}"
+      servactory_output_error: "%{message}"
+      servactory_failure_error: "%{message}"
+      regular_service_error: "%{message}"
+
+    # ============================================================================
+    # Controller DSL: Rails controller integration
+    # ============================================================================
+    controller:
+      treaty_class_not_found: "%{class_name}"

data/lib/treaty/attribute/base.rb

@@ -0,0 +1,174 @@
+# 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
+
+        raise Treaty::Exceptions::NestedAttributes,
+              I18n.t("treaty.attributes.errors.nesting_level_exceeded",
+                     level: @nesting_level,
+                     max_level: 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 [Treaty::Exceptions::NotImplemented] If subclass doesn't implement
+      # @return [void]
+      def apply_defaults!
+        # Must be implemented in subclasses
+        raise Treaty::Exceptions::NotImplemented,
+              I18n.t("treaty.attributes.errors.apply_defaults_not_implemented", class: self.class)
+      end
+
+      # Processes nested attributes block for object/array types
+      # Must be implemented in subclasses
+      #
+      # @param block [Proc] Block containing nested attribute definitions
+      # @raise [Treaty::Exceptions::NotImplemented] If subclass doesn't implement
+      # @return [void]
+      def process_nested_attributes
+        # Must be implemented in subclasses
+        raise Treaty::Exceptions::NotImplemented,
+              I18n.t("treaty.attributes.errors.process_nested_not_implemented", class: self.class)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,143 @@
+# 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 [Treaty::Exceptions::NotImplemented] If subclass doesn't implement
+        # @return [Attribute::Base] Created attribute instance
+        def create_attribute(*)
+          # Must be implemented in subclasses
+          raise Treaty::Exceptions::NotImplemented,
+                I18n.t("treaty.attributes.builder.not_implemented", class: self.class)
+        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