atlas_engine 0.1.0

data/app/models/atlas_engine/address_importer/validation/field_validations/province.rb

@@ -0,0 +1,73 @@
+# typed: true
+# frozen_string_literal: true
+
+module AtlasEngine
+  module AddressImporter
+    module Validation
+      module FieldValidations
+        class Province
+          extend T::Sig
+
+          extend T::Helpers
+          include Interface
+
+          sig { returns(String) }
+          attr_reader :country_code
+
+          sig { returns(T.nilable(String)) }
+          attr_reader :province_code
+
+          sig { returns(T::Array[String]) }
+          attr_reader :errors
+
+          sig do
+            override.params(
+              address: AddressImporter::Validation::Wrapper::AddressStruct,
+              allow_partial_zip: T::Boolean,
+            ).void
+          end
+          def initialize(address:, allow_partial_zip: false)
+            @country_code = address.country_code
+            @province_code = address.province_code
+            @errors = []
+          end
+
+          sig { override.returns(T::Array[String]) }
+          def validation_errors
+            validate_country
+            validate_province if errors.empty?
+            errors
+          end
+
+          private
+
+          sig { void }
+          def validate_country
+            errors << "Country '#{country_code}' is invalid" unless country.country?
+          end
+
+          sig { void }
+          def validate_province
+            return unless country_has_provinces?
+
+            if province_code.blank?
+              errors << "Province is required for country '#{country_code}'" unless country.province_optional?
+            elsif !country.zone(code: province_code).province?
+              errors << "Province '#{province_code}' is invalid for country '#{country_code}'"
+            end
+          end
+
+          sig { returns(Worldwide::Region) }
+          def country
+            @country ||= Worldwide.region(code: country_code)
+          end
+
+          sig { returns(T::Boolean) }
+          def country_has_provinces?
+            country.zones.present? && !country.hide_provinces_from_addresses
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/atlas_engine/address_importer/validation/field_validations/zip.rb

@@ -0,0 +1,84 @@
+# typed: true
+# frozen_string_literal: true
+
+module AtlasEngine
+  module AddressImporter
+    module Validation
+      module FieldValidations
+        class Zip
+          extend T::Sig
+          extend T::Helpers
+          include Interface
+
+          attr_reader :errors
+
+          sig do
+            override.params(
+              address: AddressImporter::Validation::Wrapper::AddressStruct,
+              allow_partial_zip: T::Boolean,
+            ).void
+          end
+          def initialize(address:, allow_partial_zip: false)
+            @country_code = address.country_code
+            @province_code = address.province_code
+            @zip = address.zip
+            @allow_partial_zip = allow_partial_zip
+            @errors = []
+          end
+
+          sig { override.returns(T::Array[String]) }
+          def validation_errors
+            validate
+            errors
+          end
+
+          private
+
+          attr_reader :country_code, :province_code, :zip
+
+          def validate
+            return unless country.country?
+
+            zip_must_match_country
+            return if errors.any?
+
+            zip_must_match_province
+          end
+
+          def zip_must_match_country
+            return unless country.has_zip?
+
+            if zip.blank? && country.zip_required?
+              errors << "Zip is required for country '#{country_code}'"
+            elsif !zip_valid_for_country?
+              errors << "Zip '#{zip}' is invalid for country '#{country_code}'"
+            end
+          end
+
+          def zip_must_match_province
+            province = country.zone(code: province_code) unless country.province_optional?
+
+            return unless province&.province?
+            return if province.valid_zip?(zip)
+            return if @allow_partial_zip && province.valid_zip?(zip, partial_match: true)
+
+            errors << "Zip '#{zip}' is invalid for province '#{province_code}'"
+          end
+
+          def zip_valid_for_country?
+            country.valid_zip?(zip) ||
+              (@allow_partial_zip && country.valid_zip?(zip, partial_match: true))
+          end
+
+          def partial_postal_code_valid_for_province?
+            country.zone(code: province_code).valid_zip?(zip, partial_match: true)
+          end
+
+          def country
+            @country ||= Worldwide.region(code: country_code)
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/atlas_engine/address_importer/validation/validator.rb

@@ -0,0 +1,17 @@
+# typed: true
+# frozen_string_literal: true
+
+module AtlasEngine
+  module AddressImporter
+    module Validation
+      module Validator
+        extend T::Sig
+        extend T::Helpers
+        interface!
+
+        sig { abstract.params(address: T.untyped).returns(T::Boolean) }
+        def valid?(address); end
+      end
+    end
+  end
+end

data/app/models/atlas_engine/address_importer/validation/wrapper.rb

@@ -0,0 +1,70 @@
+# typed: true
+# frozen_string_literal: true
+
+module AtlasEngine
+  module AddressImporter
+    module Validation
+      class Wrapper
+        extend T::Sig
+
+        include Validator
+        include ImportLogHelper
+
+        attr_reader :country_import, :validator
+
+        AddressStruct = Struct.new(:country_code, :province_code, :zip, :city, keyword_init: true)
+
+        sig do
+          params(
+            country_import: CountryImport,
+            validator: T.nilable(AddressImporter::Validation::BaseValidator),
+            log_invalid_records: T.nilable(T::Boolean),
+          ).void
+        end
+        def initialize(country_import:, validator: nil, log_invalid_records: true)
+          @country_import = country_import
+          @validator = validator || DefaultValidator.new(country_code: country_import.country_code)
+          @log_invalid_records = log_invalid_records
+        end
+
+        sig { override.params(address: T.nilable(Hash)).returns(T::Boolean) }
+        def valid?(address)
+          return false unless address
+
+          errors = validation_errors(address)
+
+          return true if errors.empty?
+
+          log_invalid_address(address, errors) if @log_invalid_records
+          false
+        end
+
+        private
+
+        sig { params(address: Hash).returns(T::Array[String]) }
+        def validation_errors(address)
+          validator.validation_errors(
+            address: address_from_hash(address),
+          ).values.flatten
+        end
+
+        sig { params(address_hash: Hash).returns(AddressStruct) }
+        def address_from_hash(address_hash)
+          AddressStruct.new(**address_hash.slice(:country_code, :province_code, :zip, :city))
+        end
+
+        sig { params(address: Hash, errors: T::Array[String]).void }
+        def log_invalid_address(address, errors)
+          errors.each do |error|
+            import_log_info(
+              country_import: country_import,
+              message: "Invalid address; #{error}",
+              category: :invalid_address,
+              additional_params: { address: address },
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/atlas_engine/address_number.rb

@@ -0,0 +1,36 @@
+# typed: strict
+# frozen_string_literal: true
+
+module AtlasEngine
+  class AddressNumber
+    extend T::Sig
+
+    sig { returns(String) }
+    attr_reader :raw
+
+    NUMBERS = /\d+/
+    NUMBERS_AND_NON_NUMBERS = %r{([A-Za-z]+|\d+\s+\d+/\d+|\d+/\d+|\d+|-)}
+
+    sig { params(value: String).void }
+    def initialize(value:)
+      @raw = value
+    end
+
+    sig { returns(T.nilable(Integer)) }
+    def to_i
+      numbers = @raw.scan(NUMBERS).flatten
+      numbers.length == 1 ? numbers[0].to_i : nil
+    end
+
+    sig { returns(T.any(Integer, Rational)) }
+    def to_r
+      fractions = @raw.scan(NUMBERS_AND_NON_NUMBERS).flatten
+      fractions[0].to_s.split.sum(&:to_r)
+    end
+
+    sig { returns(T::Array[String]) }
+    def segments
+      Array(@raw.scan(NUMBERS_AND_NON_NUMBERS).flatten)
+    end
+  end
+end

data/app/models/atlas_engine/address_number_range.rb

@@ -0,0 +1,200 @@
+# typed: true
+# frozen_string_literal: true
+
+module AtlasEngine
+  class AddressNumberRange
+    extend T::Sig
+
+    RANGE_FORMAT = %r{^\((?<min>[^\)]+)\.\.(?<max>[^\)]+)\)/(?<step>[12])$} # ex. (A1..A9)/2
+
+    class RangeError < ArgumentError; end
+
+    class << self
+      extend T::Sig
+
+      sig { params(overlapping_ranges: T::Array[T::Range[Integer]]).returns(T::Array[T::Range[Integer]]) }
+      def merge_overlapping_ranges(overlapping_ranges)
+        overlapping_ranges.sort_by(&:min).inject([]) do |ranges, range|
+          if !ranges.empty? && (ranges.last.overlaps?(range) || consecutive_ranges?(ranges.last, range))
+            ranges[0...-1] + [merge_ranges(ranges.last, range)]
+          else
+            ranges + [range]
+          end
+        end
+      end
+
+      private
+
+      sig { params(a: T::Range[Integer], b: T::Range[Integer]).returns(T::Range[Integer]) }
+      def merge_ranges(a, b)
+        [a.min, b.min].min..[a.max, b.max].max
+      end
+
+      sig { params(a: T::Range[Integer], b: T::Range[Integer]).returns(T::Boolean) }
+      def consecutive_ranges?(a, b)
+        b.min - a.max == 1
+      end
+    end
+
+    sig { params(range_string: String).void }
+    def initialize(range_string:)
+      range = RANGE_FORMAT.match(range_string)
+      if range
+        @min = AddressNumber.new(value: T.must(range[:min]))
+        @max = AddressNumber.new(value: T.must(range[:max]))
+
+        if @min.segments.length != @max.segments.length
+          raise RangeError, "min and max of range are not compatible, range_string: #{range_string}"
+        end
+
+        @step = range[:step].to_i
+      else
+        @min = AddressNumber.new(value: range_string)
+        @max = AddressNumber.new(value: range_string)
+        @step = 1
+      end
+    end
+
+    sig { params(value: String, exact_match: T::Boolean).returns(T::Boolean) }
+    def include?(value, exact_match = true)
+      value_number = AddressNumber.new(value: value)
+      value_segments = value_number.segments
+
+      if value_segments.length != format.length
+        return false if exact_match || format.length > 1
+
+        numeric_only_value = value_number.to_i
+        return false unless numeric_only_value
+
+        value_segments = [numeric_only_value.to_s]
+      end
+
+      format.each_with_index do |range_segment, i|
+        value_segment = value_segments[i]
+
+        return false unless value_segment == range_segment || range_segment.include?(value_segment)
+      end
+
+      true
+    end
+
+    sig { returns(T.nilable(T::Range[Integer])) }
+    def approx_numeric_range
+      min_numeric = @min.to_i
+      max_numeric = @max.to_i
+
+      return unless min_numeric && max_numeric
+
+      (min_numeric..max_numeric)
+    end
+
+    private
+
+    sig { returns(T::Array[T::Array[String]]) }
+    def format
+      @format ||= if include_fractions?(@min.raw) || include_fractions?(@max.raw)
+        fraction_format
+      else
+
+        min_segments = @min.segments
+        max_segments = @max.segments
+
+        range_value_format = []
+        min_segments.each_with_index do |min_segment, i|
+          max_segment = max_segments[i]
+          range_value_format << values_in_range(min_segment, max_segment)
+        end
+        range_value_format
+      end
+    end
+
+    sig { params(range_min: String, range_max: String).returns(T::Array[String]) }
+    def values_in_range(range_min, range_max)
+      (range_min..range_max).step(@step).to_a
+    end
+
+    sig { returns [T::Array[String]] }
+    def fraction_format
+      min_whole = whole_frac_value(@min.raw)
+      max_whole = whole_frac_value(@max.raw)
+
+      range_value_format = []
+
+      fractions = [
+        "",
+        "1/2",
+        "1/3",
+        "1/4",
+        "1/5",
+        "1/6",
+        "1/7",
+        "1/8",
+        "2/3",
+        "2/4",
+        "2/5",
+        "2/6",
+        "2/7",
+        "2/8",
+        "3/4",
+        "3/5",
+        "3/6",
+        "3/7",
+        "3/8",
+        "4/5",
+        "4/6",
+        "4/7",
+        "4/8",
+        "5/6",
+        "5/7",
+        "5/8",
+        "6/7",
+        "6/8",
+        "7/8",
+      ]
+
+      (min_whole..max_whole).step(@step).each do |whole|
+        fractions.each do |fraction|
+          number = build_mixed_fraction(whole, fraction)
+          address_num = AddressNumber.new(value: number)
+          range_value_format << number if address_num.to_r.between?(@min.to_r, @max.to_r)
+        end
+      end
+      [range_value_format]
+    end
+
+    sig { params(value: String).returns(T::Boolean) }
+    def include_fractions?(value)
+      %r{^([0-9]+ )?([0-9]+/[0-9]+)?$}.match?(value)
+    end
+
+    sig { params(str: String).returns(String) }
+    def whole_frac_value(str)
+      pieces = str.split(" ")
+      first_piece = T.must(pieces.first)
+      if pieces.length == 2
+        first_piece
+      elsif pieces.length == 1
+        if first_piece.include?("/")
+          "0"
+        else
+          first_piece
+        end
+      else
+        "0"
+      end
+    end
+
+    sig { params(whole_number: String, proper_fraction: String).returns(String) }
+    def build_mixed_fraction(whole_number, proper_fraction)
+      if whole_number == "0"
+        if proper_fraction == ""
+          whole_number
+        else
+          proper_fraction
+        end
+      else
+        [whole_number, proper_fraction].join(" ").strip
+      end
+    end
+  end
+end

data/app/models/atlas_engine/address_validation/abstract_address.rb

@@ -0,0 +1,49 @@
+# typed: strict
+# frozen_string_literal: true
+
+module AtlasEngine
+  module AddressValidation
+    module AbstractAddress
+      extend T::Sig
+      extend T::Helpers
+      include Kernel
+      abstract!
+      ComponentType = T.type_alias { T.nilable(String) }
+
+      sig { abstract.returns(ComponentType) }
+      def address1; end
+
+      sig { abstract.returns(ComponentType) }
+      def address2; end
+
+      sig { abstract.returns(ComponentType) }
+      def city; end
+
+      sig { abstract.returns(ComponentType) }
+      def province_code; end
+
+      sig { abstract.returns(ComponentType) }
+      def phone; end
+
+      sig { abstract.returns(ComponentType) }
+      def country_code; end
+
+      sig { abstract.returns(ComponentType) }
+      def zip; end
+
+      sig { abstract.returns(T::Hash[Symbol, String]) }
+      def to_h; end
+
+      sig { abstract.returns(T.untyped) }
+      def context; end
+
+      sig { overridable.returns(T::Enumerable[Symbol]) }
+      def keys = to_h.keys # rubocop:disable Rails/Delegate
+
+      sig { overridable.params(key: Symbol).returns(T.untyped) }
+      def [](key) = to_h[key] # rubocop:disable Rails/Delegate
+    end
+
+    TAddress = T.type_alias { AbstractAddress }
+  end
+end

data/app/models/atlas_engine/address_validation/address.rb

@@ -0,0 +1,47 @@
+# typed: strict
+# frozen_string_literal: true
+
+module AtlasEngine
+  module AddressValidation
+    class Address < T::Struct
+      extend T::Sig
+      include LogHelper
+      include AbstractAddress
+
+      ComponentType = T.type_alias { T.nilable(String) }
+      CountryType = T.type_alias { T.nilable(T.any(String, Symbol)) }
+      AddressInput = T.type_alias { Types::AddressValidation::AddressInput }
+
+      const :address1, ComponentType
+      const :address2, ComponentType
+      const :city, ComponentType
+      const :province_code, ComponentType
+      const :phone, ComponentType
+      const :country_code, CountryType
+      const :zip, ComponentType
+
+      sig { override.returns(T::Hash[Symbol, T.untyped]) }
+      def context = {}
+
+      sig { override.returns(T::Hash[Symbol, String]) }
+      def to_h = serialize.transform_keys(&:to_sym)
+
+      class << self
+        extend T::Sig
+
+        sig { params(address: TAddress).returns(Address) }
+        def from_address(address:)
+          new(
+            address1: address.address1,
+            address2: address.address2,
+            city: address.city,
+            country_code: address.country_code,
+            province_code: address.province_code,
+            zip: address.zip,
+            phone: address.phone,
+          )
+        end
+      end
+    end
+  end
+end

data/app/models/atlas_engine/address_validation/candidate.rb

@@ -0,0 +1,109 @@
+# typed: true
+# frozen_string_literal: true
+
+module AtlasEngine
+  module AddressValidation
+    class Candidate
+      extend T::Sig
+      attr_reader :id, :index
+
+      sig { params(id: String, source: Hash, index: T.nilable(String)).void }
+      def initialize(id:, source:, index: nil)
+        components_hash = Hash.new { |hash, key| hash[key] = Component.new(key, nil) }
+
+        @components = source.each_with_object(components_hash) do |(key, value), hash|
+          hash[key.to_sym] = Component.new(key.to_sym, value)
+        end
+
+        @id = id
+        @components[:id] = Component.new(:id, id)
+        @index = index
+      end
+
+      sig { params(name: Symbol).returns(T.nilable(Component)) }
+      def component(name)
+        @components[name]
+      end
+
+      sig { params(names: Symbol).returns(T::Hash[Symbol, Component]) }
+      def components(*names)
+        return @components.reject { |_, component| component.value.nil? } if names.empty?
+
+        names.index_with do |name|
+          component(name)
+        end
+      end
+
+      sig { returns(String) }
+      def serialize
+        components(:locale, :province_code, :region2, :region3, :region4, :zip, :city, :suburb, :street)
+          .values.map(&:serialize).join(",")
+      end
+
+      sig { returns(T::Boolean) }
+      def describes_po_box?
+        component(:street)&.value&.casecmp("po box") == 0
+      end
+
+      sig { returns(T::Boolean) }
+      def describes_general_delivery?
+        component(:street)&.value&.casecmp("general delivery") == 0
+      end
+
+      class << self
+        extend T::Sig
+
+        sig { params(hit: Hash).returns(Candidate) }
+        def from(hit)
+          id = hit.dig("_id")
+          source = hit.dig("_source")
+          source["city"] = source["city_aliases"].map(&:values).flatten if source["city_aliases"]
+          index = hit.dig("_index")
+          new(id: id, source: source, index: index)
+        end
+      end
+
+      class Component
+        extend T::Sig
+
+        attr_reader :name
+        attr_writer :sequences
+        attr_accessor :value
+
+        sig do
+          params(
+            name: Symbol,
+            value: T.nilable(T.any(String, Integer, Float, T::Boolean, Array, Hash, BigDecimal)),
+          ).void
+        end
+        def initialize(name, value)
+          @name = name
+          @value = value
+        end
+
+        def first_value
+          values.first
+        end
+
+        sig { returns(T::Array[AtlasEngine::AddressValidation::Token::Sequence]) }
+        def sequences
+          @sequences ||= values.map { |val| AtlasEngine::AddressValidation::Token::Sequence.from_string(val) }
+        end
+
+        sig { returns(String) }
+        def serialize
+          if value.is_a?(Array)
+            "[#{value.map(&:to_s).join(",")}]"
+          else
+            value.to_s
+          end
+        end
+
+        sig { returns(T::Array[String]) }
+        def values
+          Array(value)
+        end
+      end
+    end
+  end
+end

data/app/models/atlas_engine/address_validation/candidate_tuple.rb

@@ -0,0 +1,15 @@
+# typed: true
+# frozen_string_literal: true
+
+module AtlasEngine
+  module AddressValidation
+    CandidateTuple = Struct.new(:address_comparison, :position, :candidate) do
+      extend T::Sig
+
+      sig { params(other: CandidateTuple).returns(Integer) }
+      def <=>(other)
+        to_a[0..1] <=> other.to_a[0..1] # only consider address_comparison and position
+      end
+    end
+  end
+end