easy_talk_two 1.1.0

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/docs/.gitignore

@@ -0,0 +1,5 @@
+_site
+.sass-cache
+.jekyll-cache
+.jekyll-metadata
+vendor

data/docs/404.html

@@ -0,0 +1,25 @@
+---
+permalink: /404.html
+layout: default
+---
+
+<style type="text/css" media="screen">
+  .container {
+    margin: 10px auto;
+    max-width: 600px;
+    text-align: center;
+  }
+  h1 {
+    margin: 30px 0;
+    font-size: 4em;
+    line-height: 1;
+    letter-spacing: -1px;
+  }
+</style>
+
+<div class="container">
+  <h1>404</h1>
+
+  <p><strong>Page not found :(</strong></p>
+  <p>The requested page could not be found.</p>
+</div>

data/docs/Gemfile

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+# Hello! This is where you manage which Jekyll version is used to run.
+# When you want to use a different version, change it below, save the
+# file and run `bundle install`. Run Jekyll with `bundle exec`, like so:
+#
+#     bundle exec jekyll serve
+#
+# This will help ensure the proper Jekyll version is running.
+# Happy Jekylling!
+# gem "jekyll", "~> 4.3.3"
+gem 'github-pages', group: :jekyll_plugins
+
+gem 'webrick'
+# This is the default theme for new Jekyll sites. You may change this to anything you like.
+gem 'minima', '~> 2.5'
+# If you want to use GitHub Pages, remove the "gem "jekyll"" above and
+# uncomment the line below. To upgrade, run `bundle update github-pages`.
+# gem "github-pages", group: :jekyll_plugins
+# If you have any plugins, put them here!
+group :jekyll_plugins do
+  gem 'jekyll-feed', '~> 0.12'
+end
+
+# Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem
+# and associated library.
+platforms :mingw, :x64_mingw, :mswin, :jruby do
+  gem 'tzinfo', '>= 1', '< 3'
+  gem 'tzinfo-data'
+end
+
+# Performance-booster for watching directories on Windows
+gem 'wdm', '~> 0.1.1', platforms: %i[mingw x64_mingw mswin]
+
+# Lock `http_parser.rb` gem to `v0.6.x` on JRuby builds since newer versions of the gem
+# do not have a Java counterpart.
+gem 'http_parser.rb', '~> 0.6.0', platforms: [:jruby]

data/docs/_config.yml

@@ -0,0 +1,53 @@
+# Welcome to Jekyll!
+#
+# This config file is meant for settings that affect your whole blog, values
+# which you are expected to set up once and rarely edit after that. If you find
+# yourself editing this file very often, consider using Jekyll's data files
+# feature for the data you need to update frequently.
+#
+# For technical reasons, this file is *NOT* reloaded automatically when you use
+# 'bundle exec jekyll serve'. If you change this file, please restart the server process.
+#
+# If you need help with YAML syntax, here are some quick references for you:
+# https://learn-the-web.algonquindesign.ca/topics/markdown-yaml-cheat-sheet/#yaml
+# https://learnxinyminutes.com/docs/yaml/
+#
+# Site settings
+# These are used to personalize your new site. If you look in the HTML files,
+# you will see them accessed via {{ site.title }}, {{ site.email }}, and so on.
+# You can create any custom variable you would like, and they will be accessible
+# in the templates via {{ site.myvariable }}.
+
+title: EasyTalk 
+email: bayona.sergio@gmail.com
+description: >- # this means to ignore newlines until "baseurl:"
+  EasyTalk: define and generate JSON Schema documents.
+baseurl: "/easy_talk" # the subpath of your site, e.g. /blog
+url: "https://sergiobayona.github.io" # the base hostname & protocol for your site, e.g. http://example.com
+twitter_username: sergiobayona
+github_username:  sergiobayona
+
+# Build settings
+theme: minima
+plugins:
+  - jekyll-feed
+
+# Exclude from processing.
+# The following items will not be processed, by default.
+# Any item listed under the `exclude:` key here will be automatically added to
+# the internal "default list".
+#
+# Excluded items can be processed by explicitly listing the directories or
+# their entries' file path in the `include:` list.
+#
+# exclude:
+#   - .sass-cache/
+#   - .jekyll-cache/
+#   - gemfiles/
+#   - Gemfile
+#   - Gemfile.lock
+#   - node_modules/
+#   - vendor/bundle/
+#   - vendor/cache/
+#   - vendor/gems/
+#   - vendor/ruby/

data/docs/_posts/2024-05-07-welcome-to-jekyll.markdown

@@ -0,0 +1,29 @@
+---
+layout: post
+title:  "Welcome to Jekyll!"
+date:   2024-05-07 18:39:19 -0500
+categories: jekyll update
+---
+You’ll find this post in your `_posts` directory. Go ahead and edit it and re-build the site to see your changes. You can rebuild the site in many different ways, but the most common way is to run `jekyll serve`, which launches a web server and auto-regenerates your site when a file is updated.
+
+Jekyll requires blog post files to be named according to the following format:
+
+`YEAR-MONTH-DAY-title.MARKUP`
+
+Where `YEAR` is a four-digit number, `MONTH` and `DAY` are both two-digit numbers, and `MARKUP` is the file extension representing the format used in the file. After that, include the necessary front matter. Take a look at the source for this post to get an idea about how it works.
+
+Jekyll also offers powerful support for code snippets:
+
+{% highlight ruby %}
+def print_hi(name)
+  puts "Hi, #{name}"
+end
+print_hi('Tom')
+#=> prints 'Hi, Tom' to STDOUT.
+{% endhighlight %}
+
+Check out the [Jekyll docs][jekyll-docs] for more info on how to get the most out of Jekyll. File all bugs/feature requests at [Jekyll’s GitHub repo][jekyll-gh]. If you have questions, you can ask them on [Jekyll Talk][jekyll-talk].
+
+[jekyll-docs]: https://jekyllrb.com/docs/home
+[jekyll-gh]:   https://github.com/jekyll/jekyll
+[jekyll-talk]: https://talk.jekyllrb.com/

data/docs/about.markdown

@@ -0,0 +1,18 @@
+---
+layout: page
+title: About
+permalink: /about/
+---
+
+This is the base Jekyll theme. You can find out more info about customizing your Jekyll theme, as well as basic Jekyll usage documentation at [jekyllrb.com](https://jekyllrb.com/)
+
+You can find the source code for Minima at GitHub:
+[jekyll][jekyll-organization] /
+[minima](https://github.com/jekyll/minima)
+
+You can find the source code for Jekyll at GitHub:
+[jekyll][jekyll-organization] /
+[jekyll](https://github.com/jekyll/jekyll)
+
+
+[jekyll-organization]: https://github.com/jekyll

data/docs/index.markdown

@@ -0,0 +1,7 @@
+---
+# Feel free to add content and custom Front Matter to this file.
+# To modify the layout, see https://jekyllrb.com/docs/themes/#overriding-theme-defaults
+
+layout: home
+---
+EasyTalk is a Ruby library that simplifies defining and generating JSON Schema documents, and validates that JSON data conforms to these schemas.

data/lib/easy_talk/active_record_schema_builder.rb

@@ -0,0 +1,299 @@
+# frozen_string_literal: true
+
+module EasyTalk
+  # This class is responsible for building a SchemaDefinition from an ActiveRecord model
+  # It analyzes the database schema and creates a SchemaDefinition that can be
+  # passed to ObjectBuilder for final schema generation
+  class ActiveRecordSchemaBuilder
+    # Mapping of ActiveRecord column types to Ruby classes
+    COLUMN_TYPE_MAP = {
+      string: String,
+      text: String,
+      integer: Integer,
+      bigint: Integer,
+      float: Float,
+      decimal: Float,
+      boolean: T::Boolean,
+      date: Date,
+      datetime: DateTime,
+      timestamp: DateTime,
+      time: Time,
+      json: Hash,
+      jsonb: Hash
+    }.freeze
+
+    # Mapping for format constraints based on column type
+    FORMAT_MAP = {
+      date: 'date',
+      datetime: 'date-time',
+      timestamp: 'date-time',
+      time: 'time'
+    }.freeze
+
+    attr_reader :model
+
+    # Initialize the builder with an ActiveRecord model
+    #
+    # @param model [Class] An ActiveRecord model class
+    # @raise [ArgumentError] If the provided class is not an ActiveRecord model
+    def initialize(model)
+      raise ArgumentError, 'Class must be an ActiveRecord model' unless model.ancestors.include?(ActiveRecord::Base)
+
+      @model = model
+    end
+
+    # Build a SchemaDefinition object from the ActiveRecord model
+    #
+    # @return [EasyTalk::SchemaDefinition] A schema definition built from the database structure
+    def build_schema_definition
+      schema_def = SchemaDefinition.new(model.name)
+
+      # Apply basic schema metadata
+      apply_schema_metadata(schema_def)
+
+      # Add all database columns as properties
+      add_column_properties(schema_def)
+
+      # Add model associations as properties
+      add_association_properties(schema_def) unless EasyTalk.configuration.exclude_associations
+
+      # Add virtual properties defined in schema_enhancements
+      add_virtual_properties(schema_def)
+
+      schema_def
+    end
+
+    private
+
+    # Set top-level schema metadata like title, description, and additionalProperties
+    #
+    # @param schema_def [EasyTalk::SchemaDefinition] The schema definition to modify
+    def apply_schema_metadata(schema_def)
+      # Set title (from enhancements or derive from model name)
+      title = schema_enhancements['title'] || model.name.demodulize.humanize
+      schema_def.title(title)
+
+      # Set description if provided
+      if (description = schema_enhancements['description'])
+        schema_def.description(description)
+      end
+
+      # Set additionalProperties (from enhancements or configuration default)
+      additional_props = if schema_enhancements.key?('additionalProperties')
+                           schema_enhancements['additionalProperties']
+                         else
+                           EasyTalk.configuration.default_additional_properties
+                         end
+      schema_def.additional_properties(additional_props)
+    end
+
+    # Add properties based on database columns
+    #
+    # @param schema_def [EasyTalk::SchemaDefinition] The schema definition to modify
+    def add_column_properties(schema_def)
+      filtered_columns.each do |column|
+        # Get column enhancement info if it exists
+        column_enhancements = schema_enhancements.dig('properties', column.name.to_s) || {}
+
+        # Map the database type to Ruby type
+        ruby_type = COLUMN_TYPE_MAP.fetch(column.type, String)
+
+        # If the column is nullable, wrap the type in a Union with NilClass
+        ruby_type = T::Types::Union.new([ruby_type, NilClass]) if column.null
+
+        # Build constraints hash for this column
+        constraints = build_column_constraints(column, column_enhancements)
+
+        # Add the property to schema definition
+        schema_def.property(column.name.to_sym, ruby_type, constraints)
+      end
+    end
+
+    # Build constraints hash for a database column
+    #
+    # @param column [ActiveRecord::ConnectionAdapters::Column] The database column
+    # @param enhancements [Hash] Any schema enhancements for this column
+    # @return [Hash] The constraints hash
+    def build_column_constraints(column, enhancements)
+      constraints = {
+        optional: enhancements['optional'],
+        description: enhancements['description'],
+        title: enhancements['title']
+      }
+
+      # Add format constraint for date/time columns
+      if (format = FORMAT_MAP[column.type])
+        constraints[:format] = format
+      end
+
+      # Add max_length for string columns with limits
+      constraints[:max_length] = column.limit if column.type == :string && column.limit
+
+      # Add precision/scale for numeric columns
+      if column.type == :decimal && column.precision
+        constraints[:precision] = column.precision
+        constraints[:scale] = column.scale if column.scale
+      end
+
+      # Add default value if present and not a proc
+      if column.default && !column.default.is_a?(Proc) && column.type == :boolean
+        constraints[:default] = ActiveModel::Type::Boolean.new.cast(column.default)
+      elsif column.default && !column.default.is_a?(Proc)
+        constraints[:default] = column.default
+      end
+
+      # Remove nil values
+      constraints.compact
+    end
+
+    # Add properties based on ActiveRecord associations
+    #
+    # @param schema_def [EasyTalk::SchemaDefinition] The schema definition to modify
+    def add_association_properties(schema_def)
+      model.reflect_on_all_associations.each do |association|
+        # Skip if we can't determine the class or it's in the association exclusion list
+        next if association_excluded?(association)
+
+        # Get association enhancement info if it exists
+        assoc_enhancements = schema_enhancements.dig('properties', association.name.to_s) || {}
+
+        case association.macro
+        when :belongs_to, :has_one
+          schema_def.property(
+            association.name,
+            association.klass,
+            { optional: assoc_enhancements['optional'], description: assoc_enhancements['description'] }.compact
+          )
+        when :has_many, :has_and_belongs_to_many
+          schema_def.property(
+            association.name,
+            T::Array[association.klass],
+            { optional: assoc_enhancements['optional'], description: assoc_enhancements['description'] }.compact
+          )
+        end
+      end
+    end
+
+    # Add virtual properties defined in schema_enhancements
+    #
+    # @param schema_def [EasyTalk::SchemaDefinition] The schema definition to modify
+    def add_virtual_properties(schema_def)
+      return unless schema_enhancements['properties']
+
+      schema_enhancements['properties'].each do |name, options|
+        next unless options['virtual']
+
+        # Map string type name to Ruby class
+        ruby_type = map_type_string_to_ruby_class(options['type'] || 'string')
+
+        # Build constraints for virtual property
+        constraints = {
+          description: options['description'],
+          title: options['title'],
+          optional: options['optional'],
+          format: options['format'],
+          default: options['default'],
+          min_length: options['minLength'],
+          max_length: options['maxLength'],
+          enum: options['enum']
+        }.compact
+
+        # Add the virtual property
+        schema_def.property(name.to_sym, ruby_type, constraints)
+      end
+    end
+
+    # Map a type string to a Ruby class
+    #
+    # @param type_str [String] The type string (e.g., 'string', 'integer')
+    # @return [Class] The corresponding Ruby class
+    def map_type_string_to_ruby_class(type_str)
+      case type_str.to_s.downcase
+      when 'string' then String
+      when 'integer' then Integer
+      when 'number' then Float
+      when 'boolean' then T::Boolean
+      when 'object' then Hash
+      when 'array' then Array
+      when 'date' then Date
+      when 'datetime' then DateTime
+      when 'time' then Time
+      else String # Default fallback
+      end
+    end
+
+    # Get all columns that should be included in the schema
+    #
+    # @return [Array<ActiveRecord::ConnectionAdapters::Column>] Filtered columns
+    def filtered_columns
+      model.columns.reject do |column|
+        config = EasyTalk.configuration
+        excluded_columns.include?(column.name.to_sym) ||
+          (config.exclude_primary_key && column.name == model.primary_key) ||
+          (config.exclude_timestamps && timestamp_column?(column.name)) ||
+          (config.exclude_foreign_keys && foreign_key_column?(column.name))
+      end
+    end
+
+    # Check if a column is a timestamp column
+    #
+    # @param column_name [String] The column name
+    # @return [Boolean] True if the column is a timestamp column
+    def timestamp_column?(column_name)
+      %w[created_at updated_at].include?(column_name)
+    end
+
+    # Check if a column is a foreign key column
+    #
+    # @param column_name [String] The column name
+    # @return [Boolean] True if the column is a foreign key column
+    def foreign_key_column?(column_name)
+      column_name.end_with?('_id')
+    end
+
+    # Check if an association should be excluded
+    #
+    # @param association [ActiveRecord::Reflection::AssociationReflection] The association
+    # @return [Boolean] True if the association should be excluded
+    def association_excluded?(association)
+      !association.klass ||
+        excluded_associations.include?(association.name.to_sym) ||
+        association.options[:polymorphic] # Skip polymorphic associations (complex to model)
+    end
+
+    # Get schema enhancements
+    #
+    # @return [Hash] Schema enhancements
+    def schema_enhancements
+      @schema_enhancements ||= if model.respond_to?(:schema_enhancements)
+                                 model.schema_enhancements.deep_transform_keys(&:to_s)
+                               else
+                                 {}
+                               end
+    end
+
+    # Get all excluded columns
+    #
+    # @return [Array<Symbol>] Excluded column names
+    def excluded_columns
+      @excluded_columns ||= begin
+        config = EasyTalk.configuration
+        global_exclusions = config.excluded_columns || []
+        model_exclusions = schema_enhancements['ignore'] || []
+
+        # Combine and convert to symbols for consistent comparison
+        (global_exclusions + model_exclusions).map(&:to_sym)
+      end
+    end
+
+    # Get all excluded associations
+    #
+    # @return [Array<Symbol>] Excluded association names
+    def excluded_associations
+      @excluded_associations ||= begin
+        model_exclusions = schema_enhancements['ignore_associations'] || []
+        model_exclusions.map(&:to_sym)
+      end
+    end
+  end
+end

data/lib/easy_talk/builders/base_builder.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+# typed: true
+
+module EasyTalk
+  module Builders
+    # BaseBuilder is a class that provides a common structure for building schema properties
+    class BaseBuilder
+      extend T::Sig
+
+      # BaseBuilder is a class that provides a common structure for building objects
+      # representing schema properties.
+      COMMON_OPTIONS = {
+        title: { type: T.nilable(String), key: :title },
+        description: { type: T.nilable(String), key: :description },
+        optional: { type: T.nilable(T::Boolean), key: :optional }
+      }.freeze
+
+      attr_reader :property_name, :schema, :options
+
+      sig do
+        params(
+          property_name: Symbol,
+          schema: T::Hash[Symbol, T.untyped],
+          options: T::Hash[Symbol, String],
+          valid_options: T::Hash[Symbol, T.untyped]
+        ).void
+      end
+      # Initializes a new instance of the BaseBuilder class.
+      #
+      # @param property_name [Symbol] The name of the property.
+      # @param schema [Hash] A hash representing a json schema object.
+      # @param options [Hash] The options for the builder (default: {}).
+      # @param valid_options [Hash] The acceptable options for the given property type (default: {}).
+      def initialize(property_name, schema, options = {}, valid_options = {})
+        @valid_options = COMMON_OPTIONS.merge(valid_options)
+        EasyTalk.assert_valid_property_options(property_name, options, @valid_options.keys)
+        @property_name = property_name
+        @schema = schema
+        @options = options
+      end
+
+      # Builds the schema object based on the provided options.
+      sig { returns(T::Hash[Symbol, T.untyped]) }
+      def build
+        @valid_options.each_with_object(schema) do |(constraint_name, value), obj|
+          next if @options[constraint_name].nil?
+
+          # Use our centralized validation
+          ErrorHelper.validate_constraint_value(
+            property_name: property_name,
+            constraint_name: constraint_name,
+            value_type: value[:type],
+            value: @options[constraint_name]
+          )
+
+          obj[value[:key]] = @options[constraint_name]
+        end
+      end
+
+      def self.collection_type?
+        false
+      end
+    end
+  end
+end

data/lib/easy_talk/builders/boolean_builder.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative 'base_builder'
+
+module EasyTalk
+  module Builders
+    # Builder class for boolean properties.
+    class BooleanBuilder < BaseBuilder
+      extend T::Sig
+
+      # VALID_OPTIONS defines the valid options for a boolean property.
+      VALID_OPTIONS = {
+        enum: { type: T::Array[T::Boolean], key: :enum },
+        default: { type: T::Boolean, key: :default }
+      }.freeze
+
+      sig { params(name: Symbol, constraints: Hash).void }
+      def initialize(name, constraints = {})
+        super(name, { type: 'boolean' }, constraints, VALID_OPTIONS)
+      end
+    end
+  end
+end

data/lib/easy_talk/builders/collection_helpers.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module EasyTalk
+  module Builders
+    # Base builder class for array-type properties.
+    module CollectionHelpers
+      def collection_type?
+        true
+      end
+    end
+  end
+end

data/lib/easy_talk/builders/composition_builder.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative 'collection_helpers'
+
+module EasyTalk
+  module Builders
+    # This class represents a builder for composing JSON schemas using the "allOf", "anyOf", or "oneOf" keywords.
+    class CompositionBuilder
+      extend CollectionHelpers
+      extend T::Sig
+
+      COMPOSER_TO_KEYWORD = {
+        'AllOfBuilder' => 'allOf',
+        'AnyOfBuilder' => 'anyOf',
+        'OneOfBuilder' => 'oneOf'
+      }.freeze
+
+      sig { params(name: Symbol, type: T.untyped, _constraints: Hash).void }
+      # Initializes a new instance of the CompositionBuilder class.
+      #
+      # @param name [Symbol] The name of the composition.
+      # @param type [Class] The type of the composition.
+      # @param _constraints [Hash] The constraints for the composition (not used in this method).
+      def initialize(name, type, _constraints)
+        @composer_type = self.class.name.split('::').last
+        @name = name
+        @type = type
+        @context = {}
+      end
+
+      # Builds the composed JSON schema.
+      #
+      # @return [void]
+      def build
+        @context[@name.to_sym] = {
+          type: 'object',
+          composer_keyword => schemas
+        }
+      end
+
+      # Returns the composer keyword based on the composer type.
+      #
+      # @return [String] The composer keyword.
+      def composer_keyword
+        COMPOSER_TO_KEYWORD[@composer_type]
+      end
+
+      # Returns an array of schemas for the composed JSON schema.
+      #
+      # @return [Array<Hash>] The array of schemas.
+      def schemas
+        items.map do |type|
+          type.respond_to?(:schema) ? type.schema : { type: type.to_s.downcase }
+        end
+      end
+
+      # Returns the items of the type.
+      #
+      # @return [T.untyped] The items of the type.
+      def items
+        @type.items
+      end
+
+      # Builder class for AllOf composition.
+      class AllOfBuilder < CompositionBuilder
+      end
+
+      # Builder class for AnyOf composition.
+      class AnyOfBuilder < CompositionBuilder
+      end
+
+      # Builder class for OneOf composition.
+      class OneOfBuilder < CompositionBuilder
+      end
+    end
+  end
+end