atlas_engine 0.1.0

data/app/models/atlas_engine/address_validation/validators/full_address/components_to_validate.rb

@@ -0,0 +1,88 @@
+# typed: true
+# frozen_string_literal: true
+
+module AtlasEngine
+  module AddressValidation
+    module Validators
+      module FullAddress
+        class ComponentsToValidate
+          extend T::Sig
+
+          attr_reader :session, :candidate, :street_comparison
+
+          ALL_SUPPORTED_COMPONENTS = [
+            :province_code,
+            :city,
+            :zip,
+            :street,
+          ].freeze
+
+          sig do
+            params(
+              session: Session,
+              candidate: Candidate,
+              street_comparison: T.nilable(AtlasEngine::AddressValidation::Token::Sequence::Comparison),
+            ).void
+          end
+          def initialize(session, candidate, street_comparison)
+            @session = session
+            @candidate = candidate
+            @street_comparison = street_comparison
+          end
+
+          sig { returns(T::Array[Symbol]) }
+          def run
+            supported_components = ALL_SUPPORTED_COMPONENTS.dup - unsupported_components_for_country
+            supported_components.delete(:street) if exclude_street_validation?
+            supported_components
+          end
+
+          private
+
+          sig { returns(T::Boolean) }
+          def exclude_street_validation?
+            return true unless session.matching_strategy == AddressValidation::MatchingStrategies::EsStreet
+
+            if street_comparison.blank?
+              emit_excluded_validation("street", "not_found")
+              return true
+            end
+
+            if exclusions("street").any? { |exclusion| exclusion.apply?(session, candidate) }
+              emit_excluded_validation("street", "excluded")
+              return true
+            end
+
+            false
+          end
+
+          sig { params(component: String).returns(T::Array[T.class_of(Exclusions::ExclusionBase)]) }
+          def exclusions(component)
+            CountryProfile.for(session.country_code).validation.validation_exclusions(component: component)
+          end
+
+          sig { params(component: String, reason: String).void }
+          def emit_excluded_validation(component, reason)
+            tags = [
+              "reason:#{reason}",
+              "component:#{component}",
+              "country:#{session.country_code}",
+            ]
+            StatsD.increment("AddressValidation.skip", sample_rate: 1.0, tags: tags)
+          end
+
+          sig { returns(T::Array[Symbol]) }
+          def unsupported_components_for_country
+            unsupported_components = []
+            country = Worldwide.region(code: session.address.country_code)
+            unsupported_components << :province_code if country.province_optional?
+            unsupported_components << :province_code if country.hide_provinces_from_addresses
+            unsupported_components << :city unless country.city_required?
+            unsupported_components << :zip unless country.zip_required? && !country.zip_autofill_enabled
+            unsupported_components.uniq
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/atlas_engine/address_validation/validators/full_address/concern_builder.rb

@@ -0,0 +1,127 @@
+# typed: true
+# frozen_string_literal: true
+
+module AtlasEngine
+  module AddressValidation
+    module Validators
+      module FullAddress
+        class ConcernBuilder
+          extend T::Sig
+
+          attr_reader :unmatched_component, :unmatched_field, :matched_components, :address, :suggestion_ids
+
+          UNMATCHED_COMPONENTS_SUGGESTION_THRESHOLD = 2
+
+          class << self
+            extend T::Sig
+
+            sig do
+              params(
+                address: AbstractAddress,
+                unmatched_component_keys: T::Array[Symbol],
+              ).returns(T::Boolean)
+            end
+            def should_suggest?(address, unmatched_component_keys)
+              return false if too_many_unmatched_components?(unmatched_component_keys)
+
+              return false if province_and_city_xor_zip?(unmatched_component_keys) && !valid_zip_for_province?(address)
+
+              true
+            end
+
+            sig { params(unmatched_component_keys: T::Array[Symbol]).returns(T::Boolean) }
+            def too_many_unmatched_components?(unmatched_component_keys)
+              unmatched_component_keys.size > UNMATCHED_COMPONENTS_SUGGESTION_THRESHOLD
+            end
+
+            sig { params(address: AbstractAddress).returns(T::Boolean) }
+            def valid_zip_for_province?(address)
+              !country_has_zip_codes(address) || province_postal_code_valid?(address)
+            end
+
+            private
+
+            sig { params(component_keys: T::Array[Symbol]).returns(T::Boolean) }
+            def province_and_city_xor_zip?(component_keys)
+              component_keys.include?(:province_code) && component_keys.intersection([:zip, :city]).one?
+            end
+
+            sig { params(address: AbstractAddress).returns(T::Boolean) }
+            def country_has_zip_codes(address)
+              Worldwide.region(code: address.country_code).has_zip?
+            end
+
+            def province_postal_code_valid?(address)
+              return true if address.province_code.blank?
+
+              country = Worldwide.region(code: address.country_code)
+              return true if country.hide_provinces_from_addresses
+
+              province = country.zone(code: address.province_code)
+              return true unless province.province?
+
+              province.valid_zip?(address.zip)
+            end
+          end
+
+          sig do
+            params(
+              unmatched_component: Symbol,
+              matched_components: T::Array[Symbol],
+              address: AbstractAddress,
+              suggestion_ids: T::Array[String],
+              unmatched_field: T.nilable(Symbol),
+            ).void
+          end
+          def initialize(unmatched_component:, matched_components:, address:, suggestion_ids:, unmatched_field: nil)
+            @unmatched_component = unmatched_component
+            @unmatched_field = unmatched_field
+            @matched_components = matched_components
+            @address = address
+            @suggestion_ids = suggestion_ids
+          end
+
+          sig { returns(AddressValidation::Concern) }
+          def build
+            case unmatched_component
+            when :zip
+              build_zip_concern
+            when :province_code
+              build_province_concern
+            else
+              build_default_concern
+            end
+          end
+
+          private
+
+          sig { returns(AddressValidation::Concern) }
+          def build_zip_concern
+            concern = InvalidZipConcernBuilder.for(address, suggestion_ids)
+            return concern if concern
+
+            if :province_code.in?(matched_components) && :city.in?(matched_components)
+              return UnknownZipForAddressConcern.new(address, suggestion_ids)
+            end
+
+            build_default_concern
+          end
+
+          sig { returns(AddressValidation::Concern) }
+          def build_province_concern
+            if ([:zip, :city] - matched_components).empty?
+              UnknownProvinceConcern.new(address, suggestion_ids)
+            else
+              build_default_concern
+            end
+          end
+
+          sig { returns(AddressValidation::Concern) }
+          def build_default_concern
+            UnmatchedFieldConcern.new(unmatched_component, matched_components, address, suggestion_ids, unmatched_field)
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/atlas_engine/address_validation/validators/full_address/exclusions/exclusion_base.rb

@@ -0,0 +1,23 @@
+# typed: true
+# frozen_string_literal: true
+
+module AtlasEngine
+  module AddressValidation
+    module Validators
+      module FullAddress
+        module Exclusions
+          class ExclusionBase
+            class << self
+              extend T::Sig
+              extend T::Helpers
+              abstract!
+
+              sig { abstract.params(session: Session, candidate: Candidate).returns(T::Boolean) }
+              def apply?(session, candidate); end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/atlas_engine/address_validation/validators/full_address/invalid_zip_concern_builder.rb

@@ -0,0 +1,42 @@
+# typed: true
+# frozen_string_literal: true
+
+module AtlasEngine
+  module AddressValidation
+    module Validators
+      module FullAddress
+        class InvalidZipConcernBuilder
+          class << self
+            extend T::Sig
+
+            sig do
+              params(
+                address: AbstractAddress,
+                suggestion_ids: T::Array[String],
+              ).returns(T.nilable(AddressValidation::Concern))
+            end
+            def for(address, suggestion_ids)
+              country = Worldwide.region(code: address.country_code)
+
+              province = country.zone(code: address.province_code.presence || "")
+              return unless country.has_zip?
+
+              if country_expects_zone_in_address?(country) && province.province?
+                InvalidZipForProvinceConcern.new(address, suggestion_ids) unless province.valid_zip?(address.zip)
+              else
+                InvalidZipForCountryConcern.new(address, suggestion_ids) unless country.valid_zip?(address.zip)
+              end
+            end
+
+            private
+
+            sig { params(country: Worldwide::Region).returns(T::Boolean) }
+            def country_expects_zone_in_address?(country)
+              country.zones&.any?(&:province?) && !country.hide_provinces_from_addresses
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/atlas_engine/address_validation/validators/full_address/invalid_zip_for_country_concern.rb

@@ -0,0 +1,37 @@
+# typed: true
+# frozen_string_literal: true
+
+module AtlasEngine
+  module AddressValidation
+    module Validators
+      module FullAddress
+        class InvalidZipForCountryConcern < AddressValidation::Concern
+          include ConcernFormatter
+          attr_reader :address
+
+          sig { params(address: AbstractAddress, suggestion_ids: T::Array[String]).void }
+          def initialize(address, suggestion_ids)
+            @address = address
+
+            super(
+              code: :zip_invalid_for_country,
+              field_names: [:zip],
+              message: message,
+              type: T.must(Concern::TYPES[:error]),
+              type_level: 1,
+              suggestion_ids: suggestion_ids
+            )
+          end
+
+          sig { returns(String) }
+          def message
+            country.field(key: :zip).error(
+              code: :invalid_for_country,
+              options: { country: country.full_name },
+            ).to_s
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/atlas_engine/address_validation/validators/full_address/invalid_zip_for_province_concern.rb

@@ -0,0 +1,37 @@
+# typed: true
+# frozen_string_literal: true
+
+module AtlasEngine
+  module AddressValidation
+    module Validators
+      module FullAddress
+        class InvalidZipForProvinceConcern < AddressValidation::Concern
+          include ConcernFormatter
+          attr_reader :address
+
+          sig { params(address: AbstractAddress, suggestion_ids: T::Array[String]).void }
+          def initialize(address, suggestion_ids)
+            @address = address
+
+            super(
+              code: :zip_invalid_for_province,
+              field_names: [:zip],
+              message: message,
+              type: T.must(Concern::TYPES[:error]),
+              type_level: 1,
+              suggestion_ids: suggestion_ids
+            )
+          end
+
+          sig { returns(String) }
+          def message
+            country.field(key: :zip).error(
+              code: :invalid_for_province,
+              options: { province: province_name },
+            ).to_s
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/atlas_engine/address_validation/validators/full_address/no_candidate_result.rb

@@ -0,0 +1,26 @@
+# typed: true
+# frozen_string_literal: true
+
+module AtlasEngine
+  module AddressValidation
+    module Validators
+      module FullAddress
+        class NoCandidateResult < CandidateResultBase
+          extend T::Sig
+
+          sig { void }
+          def update_result
+            result.concerns << UnknownAddressConcern.new(
+              address,
+            )
+
+            concern = InvalidZipConcernBuilder.for(session.address, [])
+            result.concerns << concern if concern
+
+            update_result_scope
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/atlas_engine/address_validation/validators/full_address/number_comparison.rb

@@ -0,0 +1,31 @@
+# typed: true
+# frozen_string_literal: true
+
+module AtlasEngine
+  module AddressValidation
+    module Validators
+      module FullAddress
+        class NumberComparison
+          include Comparable
+
+          attr_reader :numbers, :candidate_ranges
+
+          def initialize(numbers: [], candidate_ranges: [])
+            @numbers = numbers
+            @candidate_ranges = candidate_ranges
+          end
+
+          def match?
+            return true if candidate_ranges.blank? && numbers.present?
+
+            numbers.compact.any? do |number|
+              candidate_ranges.any? do |candidate_range|
+                candidate_range.include?(number)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/atlas_engine/address_validation/validators/full_address/postal_code_matcher.rb

@@ -0,0 +1,60 @@
+# typed: true
+# frozen_string_literal: true
+
+# This class is responsible for checking whether the session postal code is a valid partial length.
+# If valid, #truncate will return a truncated candidate postal code that corresponds to a valid partial range.
+# Else, #truncate will return the unmodified candidate postal code.
+
+module AtlasEngine
+  module AddressValidation
+    module Validators
+      module FullAddress
+        class PostalCodeMatcher
+          extend T::Sig
+          include LogHelper
+
+          attr_reader :country_code, :session_postal_code, :candidate_postal_code
+
+          sig do
+            params(country_code: String, session_postal_code: String, candidate_postal_code: T.nilable(String)).void
+          end
+          def initialize(country_code, session_postal_code, candidate_postal_code = nil)
+            @country_code = country_code
+            @session_postal_code = session_postal_code
+            @candidate_postal_code = candidate_postal_code
+          end
+
+          sig { returns(T.nilable(String)) }
+          def truncate
+            return unless candidate_postal_code
+            return candidate_postal_code if candidate_postal_code.size <= session_postal_code.size
+            return candidate_postal_code unless valid_partial_postal_code_length?
+
+            truncated_postal_code = candidate_postal_code[partial_postal_code_range]
+
+            log_info("Truncating candidate postal code", {
+              session_postal_code: session_postal_code,
+              original_postal_code: candidate_postal_code,
+              truncated_postal_code: truncated_postal_code,
+            })
+
+            truncated_postal_code
+          end
+
+          private
+
+          sig { returns(T::Boolean) }
+          def valid_partial_postal_code_length?
+            partial_postal_code_range.present?
+          end
+
+          sig { returns(T.nilable(Range)) }
+          def partial_postal_code_range
+            @partial_postal_code_range ||= CountryProfile.for(country_code)
+              .validation.partial_postal_code_range(session_postal_code.size)
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/atlas_engine/address_validation/validators/full_address/result_updater.rb

@@ -0,0 +1,42 @@
+# typed: true
+# frozen_string_literal: true
+
+module AtlasEngine
+  module AddressValidation
+    module Validators
+      module FullAddress
+        class ResultUpdater
+          extend T::Sig
+          extend T::Helpers
+          abstract!
+
+          sig { params(session: Session, result: Result).void }
+          def initialize(session:, result:)
+            @session = session
+            @result = result
+          end
+
+          private
+
+          attr_reader :session, :result
+
+          delegate :address, to: :session
+
+          sig { void }
+          def update_result_scope
+            concern_fields = result.concerns.flat_map(&:field_names).uniq
+            scopes_to_remove = concern_fields.flat_map { |field| contained_scopes_for(field) }
+            result.validation_scope.reject! { |scope| scope.in?(scopes_to_remove) }
+          end
+
+          sig { params(scope: Symbol).returns(T.nilable(T::Array[Symbol])) }
+          def contained_scopes_for(scope)
+            return [] unless (scope_index = Result::SORTED_VALIDATION_SCOPES.index(scope))
+
+            Result::SORTED_VALIDATION_SCOPES.slice(scope_index..)
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/atlas_engine/address_validation/validators/full_address/suggestion_builder.rb

@@ -0,0 +1,140 @@
+# typed: true
+# frozen_string_literal: true
+
+module AtlasEngine
+  module AddressValidation
+    module Validators
+      module FullAddress
+        class SuggestionBuilder
+          class << self
+            extend T::Sig
+            sig do
+              params(
+                address: {
+                  address1: T.nilable(String),
+                  address2: T.nilable(String),
+                  city: T.nilable(String),
+                  province_code: T.nilable(String),
+                  country_code: T.nilable(String),
+                  zip: T.nilable(String),
+                  phone: T.nilable(String),
+                },
+                comparisons: T::Hash[Symbol, AtlasEngine::AddressValidation::Token::Sequence::Comparison],
+                candidate: AddressValidation::Candidate,
+                unmatched_fields: T::Hash[Symbol, Symbol],
+              ).returns(Suggestion)
+            end
+            def from_comparisons(address, comparisons, candidate, unmatched_fields = {})
+              unmatched_address_keys = comparisons.keys.each_with_object([]) do |key, array|
+                array << if key == :street
+                  unmatched_fields[:street]
+                else
+                  key
+                end
+              end.append(:country_code).compact
+
+              suggestion = Suggestion.new(**T.unsafe(address).slice(*unmatched_address_keys))
+
+              comparisons.each do |key, comparison|
+                # suggestion.send("suggest_#{key}", comparison, candidate, unmatched_fields)
+                case key
+                when :street
+                  suggest_street(suggestion, comparison, candidate, unmatched_fields)
+                when :city
+                  suggest_city(suggestion, comparison, candidate, unmatched_fields)
+                when :zip
+                  suggest_zip(suggestion, comparison, candidate, unmatched_fields)
+                when :province_code
+                  suggest_province_code(suggestion, comparison, candidate, unmatched_fields)
+                end
+              end
+
+              # Since the suggestion does not suggest the new country, we can safely remove it.
+              suggestion.country_code = nil
+
+              suggestion
+            end
+
+            private
+
+            sig do
+              params(
+                suggestion: Suggestion,
+                comparison: AtlasEngine::AddressValidation::Token::Sequence::Comparison,
+                candidate: AddressValidation::Candidate,
+                unmatched_fields: T::Hash[Symbol, Symbol],
+              ).returns(Suggestion)
+            end
+            def suggest_street(suggestion, comparison, candidate, unmatched_fields)
+              suggested_street = comparison.right_sequence.raw_value
+              original_street = comparison.left_sequence.raw_value
+              field = unmatched_fields[:street]
+
+              if field == :address1
+                suggestion.address1 = suggestion.address1.to_s.sub(original_street, suggested_street)
+              elsif field == :address2
+                suggestion.address2 = suggestion.address2.to_s.sub(original_street, suggested_street)
+              end
+
+              suggestion
+            end
+
+            sig do
+              params(
+                suggestion: Suggestion,
+                comparison: AtlasEngine::AddressValidation::Token::Sequence::Comparison,
+                candidate: AddressValidation::Candidate,
+                _unmatched_fields: T::Hash[Symbol, Symbol],
+              ).returns(Suggestion)
+            end
+            def suggest_city(suggestion, comparison, candidate, _unmatched_fields)
+              suggestion.city = generic_field_suggestion(comparison, candidate, :city)
+              suggestion
+            end
+
+            sig do
+              params(
+                suggestion: Suggestion,
+                comparison: AtlasEngine::AddressValidation::Token::Sequence::Comparison,
+                candidate: AddressValidation::Candidate,
+                _unmatched_fields: T::Hash[Symbol, Symbol],
+              ).returns(Suggestion)
+            end
+            def suggest_zip(suggestion, comparison, candidate, _unmatched_fields)
+              suggestion.zip = generic_field_suggestion(comparison, candidate, :zip)
+              suggestion
+            end
+
+            sig do
+              params(
+                suggestion: Suggestion,
+                comparison: AtlasEngine::AddressValidation::Token::Sequence::Comparison,
+                candidate: AddressValidation::Candidate,
+                _unmatched_fields: T::Hash[Symbol, Symbol],
+              ).returns(Suggestion)
+            end
+            def suggest_province_code(suggestion, comparison, candidate, _unmatched_fields)
+              suggestion.province_code = generic_field_suggestion(comparison, candidate, :province_code)
+              suggestion
+            end
+
+            sig do
+              params(
+                comparison: AtlasEngine::AddressValidation::Token::Sequence::Comparison,
+                candidate: AddressValidation::Candidate,
+                field: Symbol,
+              ).returns(String)
+            end
+            def generic_field_suggestion(comparison, candidate, field)
+              if comparison.token_match_count == 0 || comparison.aggregate_edit_distance > 2
+                candidate.component(field)&.first_value
+              else
+                comparison.right_sequence.raw_value
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/atlas_engine/address_validation/validators/full_address/unknown_address_concern.rb

@@ -0,0 +1,30 @@
+# typed: true
+# frozen_string_literal: true
+
+module AtlasEngine
+  module AddressValidation
+    module Validators
+      module FullAddress
+        class UnknownAddressConcern < AddressValidation::Concern
+          include ConcernFormatter
+
+          sig { returns(TAddress) }
+          attr_reader :address
+
+          sig { params(address: TAddress).void }
+          def initialize(address)
+            @address = address
+            super(
+              code: :address_unknown,
+              message: Worldwide.region(code: address.country_code).field(key: :address).error(code: :may_not_exist),
+              type: T.must(Concern::TYPES[:warning]),
+              type_level: 1,
+              suggestion_ids: [],
+              field_names: [:address1],
+            )
+          end
+        end
+      end
+    end
+  end
+end