zxcvbn-ruby 1.4.0 → 2.0.0

data/lib/zxcvbn/guesses.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require 'zxcvbn/math'
+
+module Zxcvbn
+  # Mixin that provides guesses estimation for each match pattern.
+  #
+  # Each pattern-specific method returns a raw guess count; {estimate_guesses}
+  # applies a per-token minimum and memoises the result on the match object.
+  # Mirrors the guesses estimation logic from zxcvbn.js v4.
+  # @api private
+  module Guesses
+    include Zxcvbn::Math
+
+    MIN_GUESSES_BEFORE_GROWING_SEQUENCE = 10_000
+    MIN_SUBMATCH_GUESSES_SINGLE_CHAR    = 10
+    MIN_SUBMATCH_GUESSES_MULTI_CHAR     = 50
+    BRUTEFORCE_CARDINALITY              = 10
+    MIN_YEAR_SPACE                      = 20
+
+    START_UPPER = /^[A-Z][^A-Z]+$/
+    END_UPPER   = /^[^A-Z]+[A-Z]$/
+    ALL_UPPER   = /^[^a-z]+$/
+    ALL_LOWER   = /^[^A-Z]+$/
+
+    # Estimate the number of guesses required to crack a match.
+    #
+    # Mutates the builder in place: sets guesses, guesses_log10, and any
+    # pattern-specific fields (base_guesses, uppercase_variations, l33t_variations).
+    # Returns immediately if guesses are already set.
+    #
+    # @param match [MatchBuilder] the builder to estimate
+    # @param password [String] the full password being evaluated
+    # @return [Numeric] the estimated guess count
+    def estimate_guesses(match, password)
+      return match.guesses if match.guesses
+
+      token_length = match.token ? match.token.length : match.j - match.i + 1
+      min_guesses =
+        if token_length < password.length
+          token_length == 1 ? MIN_SUBMATCH_GUESSES_SINGLE_CHAR : MIN_SUBMATCH_GUESSES_MULTI_CHAR
+        else
+          1
+        end
+
+      guesses =
+        case match.pattern
+        in 'bruteforce' then bruteforce_guesses(match)
+        in 'dictionary' then dictionary_guesses(match)
+        in 'spatial'    then spatial_guesses(match)
+        in 'repeat'     then repeat_guesses(match)
+        in 'sequence'   then sequence_guesses(match)
+        in 'digits'     then digits_guesses(match)
+        in 'year'       then year_guesses(match)
+        in 'date'       then date_guesses(match)
+        else 1
+        end
+
+      match.guesses = [guesses, min_guesses].max
+      match.guesses_log10 = ::Math.log10(match.guesses)
+      match.guesses
+    end
+
+    # @param match [MatchBuilder] a bruteforce match
+    # @return [Numeric] guesses based on token length and assumed cardinality
+    def bruteforce_guesses(match)
+      length = match.token ? match.token.length : match.j - match.i + 1
+      guesses = BRUTEFORCE_CARDINALITY**length.to_f
+      guesses = Float::MAX if guesses.infinite?
+      min = length == 1 ? MIN_SUBMATCH_GUESSES_SINGLE_CHAR + 1.0 : MIN_SUBMATCH_GUESSES_MULTI_CHAR + 1.0
+      [guesses, min].max
+    end
+
+    # @param match [MatchBuilder] a sequence match (e.g. "abc", "6543")
+    # @return [Integer] guesses based on sequence type and direction
+    def sequence_guesses(match)
+      first_char = match.token[0]
+      base_guesses =
+        if %w[a A z Z 0 1 9].include?(first_char)
+          4
+        elsif first_char.match?(/\d/)
+          10
+        else
+          26
+        end
+      base_guesses *= 2 unless match.ascending
+      base_guesses * match.token.length
+    end
+
+    # @param match [MatchBuilder] a digits match
+    # @return [Integer] 10^length (all possible digit strings of that length)
+    def digits_guesses(match)
+      10**match.token.length
+    end
+
+    # @param match [MatchBuilder] a year match
+    # @return [Integer] distance from the current year, floored at {MIN_YEAR_SPACE}
+    def year_guesses(match)
+      [(match.token.to_i - reference_year).abs, MIN_YEAR_SPACE].max
+    end
+
+    # @param match [MatchBuilder] a date match with year and separator set
+    # @return [Integer] 365 * year_space, multiplied by 4 if a separator is present
+    def date_guesses(match)
+      year_space = [(match.year - reference_year).abs, MIN_YEAR_SPACE].max
+      guesses = 365 * year_space
+      guesses *= 4 if match.separator && !match.separator.empty?
+      guesses
+    end
+
+    # @param match [MatchBuilder] a spatial (keyboard pattern) match
+    # @return [Numeric] guesses based on graph topology, turns, and shifted keys
+    def spatial_guesses(match)
+      if %w[qwerty dvorak].include?(match.graph)
+        s = starting_positions_for_graph('qwerty')
+        d = average_degree_for_graph('qwerty')
+      else
+        s = starting_positions_for_graph('keypad')
+        d = average_degree_for_graph('keypad')
+      end
+
+      guesses = 0
+      token_length = match.token.length
+      turns = match.turns
+      (2..token_length).each do |i|
+        possible_turns = [turns, i - 1].min
+        (1..possible_turns).each do |j|
+          guesses += nCk(i - 1, j - 1) * s * (d**j)
+        end
+      end
+
+      if match.shifted_count&.positive?
+        shifted   = match.shifted_count
+        unshifted = token_length - match.shifted_count
+        if unshifted.zero?
+          guesses *= 2
+        else
+          shift_variations = 0
+          (1..[shifted, unshifted].min).each { |i| shift_variations += nCk(shifted + unshifted, i) }
+          guesses *= shift_variations
+        end
+      end
+
+      guesses
+    end
+
+    # @param match [MatchBuilder] a dictionary match
+    # @return [Integer] rank multiplied by uppercase and l33t variation counts,
+    #   plus a factor of 2 if the word was matched in reverse
+    def dictionary_guesses(match)
+      match.base_guesses = match.rank
+      match.uppercase_variations = uppercase_variations(match)
+      match.l33t_variations      = l33t_variations(match)
+      reversed_multiplier        = match.reversed ? 2 : 1
+      match.base_guesses * match.uppercase_variations * match.l33t_variations * reversed_multiplier
+    end
+
+    # Count the number of ways the token's capitalisation could have been chosen.
+    #
+    # Returns 1 for all-lowercase or already-lowercase words. Returns 2 for
+    # simple patterns (StartUpper, endUPPER, ALLCAPS). Otherwise returns the
+    # sum of combinations for mixed-case tokens.
+    #
+    # @param match [MatchBuilder] a dictionary match
+    # @return [Integer] uppercase variation multiplier
+    def uppercase_variations(match)
+      word = match.token
+      return 1 if word.match?(ALL_LOWER) || word.downcase == word
+
+      [START_UPPER, END_UPPER, ALL_UPPER].each { |r| return 2 if word.match?(r) }
+
+      num_upper = word.chars.count { |c| c.match?(/[A-Z]/) }
+      num_lower = word.chars.count { |c| c.match?(/[a-z]/) }
+      variations = 0
+      (1..[num_upper, num_lower].min).each { |i| variations += nCk(num_upper + num_lower, i) }
+      variations
+    end
+
+    # Count the number of ways the token's l33t substitutions could have been chosen.
+    #
+    # Returns 1 if the match has no l33t substitutions. Otherwise multiplies
+    # the variation count for each substituted character pair using combinations.
+    #
+    # @param match [MatchBuilder] a dictionary match, possibly with l33t substitutions
+    # @return [Integer] l33t variation multiplier
+    def l33t_variations(match)
+      return 1 unless match.l33t && match.sub
+
+      variations = 1
+      match.sub.each do |subbed, unsubbed|
+        chars        = match.token.downcase.chars
+        num_subbed   = chars.count { |c| c == subbed }
+        num_unsubbed = chars.count { |c| c == unsubbed }
+        if num_subbed.zero? || num_unsubbed.zero?
+          variations *= 2
+        else
+          p = [num_subbed, num_unsubbed].min
+          sub_variations = 0
+          (1..p).each { |i| sub_variations += nCk(num_subbed + num_unsubbed, i) }
+          variations *= sub_variations
+        end
+      end
+      variations
+    end
+
+    attr_reader :reference_year
+  end
+end

data/lib/zxcvbn/match.rb

@@ -1,24 +1,104 @@
 # frozen_string_literal: true
 
 module Zxcvbn
-  class Match
-    attr_accessor :pattern, :i, :j, :token, :matched_word, :rank,
-                  :dictionary_name, :reversed, :l33t, :sub, :sub_display,
-                  :l, :entropy, :base_entropy, :uppercase_entropy, :l33t_entropy,
-                  :repeated_char, :sequence_name, :sequence_space, :ascending,
-                  :graph, :turns, :shifted_count, :shiffted_count,
-                  :year, :month, :day, :separator, :cardinality, :offset
+  # A substring match found by one of the pattern matchers.
+  #
+  # All attributes are optional and default to +nil+. Use {#with} to derive a
+  # new match with changed attributes.
+  #
+  # @!attribute [r] pattern
+  #   @return [String, nil] the matcher that produced this match
+  # @!attribute [r] i
+  #   @return [Integer, nil] start index in the password (inclusive)
+  # @!attribute [r] j
+  #   @return [Integer, nil] end index in the password (inclusive)
+  # @!attribute [r] token
+  #   @return [String, nil] the matched substring
+  # @!attribute [r] matched_word
+  #   @return [String, nil] lowercased dictionary word (dictionary matches)
+  # @!attribute [r] rank
+  #   @return [Integer, nil] frequency rank of the matched word (dictionary matches)
+  # @!attribute [r] dictionary_name
+  #   @return [String, nil] source dictionary name (dictionary matches)
+  # @!attribute [r] reversed
+  #   @return [Boolean, nil] true when matched in the reversed password
+  # @!attribute [r] l33t
+  #   @return [Boolean, nil] true when the match required l33t substitution
+  # @!attribute [r] sub
+  #   @return [Hash, nil] map of l33t characters to their substituted letters
+  # @!attribute [r] sub_display
+  #   @return [String, nil] human-readable substitution summary
+  # @!attribute [r] guesses
+  #   @return [Numeric, nil] estimated guess count
+  # @!attribute [r] guesses_log10
+  #   @return [Float, nil] log10 of {#guesses}
+  # @!attribute [r] base_guesses
+  #   @return [Numeric, nil] guesses for the base token (repeat matches) or
+  #     rank before variation multipliers (dictionary matches)
+  # @!attribute [r] uppercase_variations
+  #   @return [Numeric, nil] capitalisation variant count (dictionary matches)
+  # @!attribute [r] l33t_variations
+  #   @return [Numeric, nil] l33t substitution variant count (dictionary matches)
+  # @!attribute [r] base_token
+  #   @return [String, nil] the minimal repeating unit (repeat matches)
+  # @!attribute [r] repeat_count
+  #   @return [Integer, nil] number of repetitions (repeat matches)
+  # @!attribute [r] sequence_name
+  #   @return [String, nil] sequence type: "lower", "upper", "digits", or "unicode"
+  # @!attribute [r] sequence_space
+  #   @return [Integer, nil] size of the character set for the sequence
+  # @!attribute [r] ascending
+  #   @return [Boolean, nil] true if the sequence is ascending
+  # @!attribute [r] graph
+  #   @return [String, nil] keyboard graph name (spatial matches)
+  # @!attribute [r] turns
+  #   @return [Integer, nil] number of direction changes (spatial matches)
+  # @!attribute [r] shifted_count
+  #   @return [Integer, nil] number of shifted characters (spatial matches)
+  # @!attribute [r] year
+  #   @return [Integer, nil] matched year (date/year matches)
+  # @!attribute [r] month
+  #   @return [Integer, nil] matched month (date matches)
+  # @!attribute [r] day
+  #   @return [Integer, nil] matched day (date matches)
+  # @!attribute [r] separator
+  #   @return [String, nil] date separator character (date matches)
+  Match = ::Data.define(
+    :pattern, :i, :j, :token, :matched_word, :rank, :dictionary_name, :reversed,
+    :l33t, :sub, :sub_display, :guesses, :guesses_log10, :base_guesses,
+    :uppercase_variations, :l33t_variations, :base_token, :repeat_count,
+    :sequence_name, :sequence_space, :ascending, :graph, :turns, :shifted_count,
+    :year, :month, :day, :separator
+  ) do
+    def initialize(
+      pattern: nil, i: nil, j: nil, token: nil, matched_word: nil, rank: nil,
+      dictionary_name: nil, reversed: nil, l33t: nil, sub: nil,
+      sub_display: nil, guesses: nil, guesses_log10: nil, base_guesses: nil,
+      uppercase_variations: nil, l33t_variations: nil, base_token: nil,
+      repeat_count: nil, sequence_name: nil, sequence_space: nil,
+      ascending: nil, graph: nil, turns: nil, shifted_count: nil,
+      year: nil, month: nil, day: nil, separator: nil
+    )
+      super
+    end
 
-    def initialize(**attributes)
-      attributes.each do |key, value|
-        instance_variable_set("@#{key}", value)
-      end
+    # @return [String] a human-readable representation omitting nil fields and token
+    def inspect
+      fields = to_h.reject { |k, v| v.nil? || k == :token }.map { |k, v| "#{k}=#{v.inspect}" }.join(', ')
+      "#<data #{self.class} #{fields}>"
     end
 
-    def to_hash
-      instance_variables.sort.each_with_object({}) do |var, hash|
-        key = var.to_s.delete_prefix('@')
-        hash[key] = instance_variable_get(var)
+    # @param pp [PP] the pretty-printer instance
+    # @return [void]
+    def pretty_print(pp)
+      fields = to_h.reject { |_, v| v.nil? }
+      pp.group(1, "#<data #{self.class}", '>') do
+        fields.each_with_index do |(k, v), i|
+          pp.text(',') if i.positive?
+          pp.breakable ' '
+          pp.text("#{k}=")
+          v.pretty_print(pp)
+        end
       end
     end
   end

data/lib/zxcvbn/match_builder.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'zxcvbn/match'
+
+module Zxcvbn
+  # Mutable accumulator for match attributes. Matchers populate a builder
+  # incrementally; {#build} seals it into an immutable {Match}.
+  # @api private
+  MatchBuilder = Struct.new(*Match.members, keyword_init: true) do
+    # @return [Match] immutable match with the current attribute values
+    def build
+      Match.new(**to_h.tap { |h| h[:sub]&.freeze })
+    end
+  end
+end

data/lib/zxcvbn/matchers/date.rb

@@ -1,139 +1,204 @@
 # frozen_string_literal: true
 
-require 'zxcvbn/matchers/regex_helpers'
-
 module Zxcvbn
   module Matchers
+    # Matches date patterns in passwords, both with and without separators.
+    # Ported from the zxcvbn v4 JavaScript implementation's +date_match+ function.
+    # @api private
     class Date
-      include RegexHelpers
-
-      YEAR_SUFFIX = %r{
-        ( \d{1,2} )                         # day or month
-        ( \s | - | / | \\ | _ | \. )        # separator
-        ( \d{1,2} )                         # month or day
-        \2                                  # same separator
-        ( 19\d{2} | 200\d | 201\d | \d{2} ) # year
-      }x.freeze
-
-      YEAR_PREFIX = %r{
-        ( 19\d{2} | 200\d | 201\d | \d{2} ) # year
-        ( \s | - | / | \\ | _ | \. )        # separator
-        ( \d{1,2} )                         # day or month
-        \2                                  # same separator
-        ( \d{1,2} )                         # month or day
-      }x.freeze
-
-      WITHOUT_SEPARATOR = /\d{4,8}/.freeze
-
-      def matches(password)
-        match_with_separator(password) + match_without_separator(password)
+      # Matches a separator-based date substring (e.g. "02/12/1997", "97-12-02").
+      # The first and last groups each allow 1–4 digits so the year may appear in
+      # either position; {map_ints_to_dmy} resolves which group is the year.
+      MAYBE_DATE_WITH_SEP = %r{\A(\d{1,4})([\s/\\_.-])(\d{1,2})\2(\d{1,4})\z}
+
+      # Matches a run of digits that could be a date without separators.
+      MAYBE_DATE_WITHOUT_SEP = /\A\d+\z/
+
+      # Maps token length to split-point pairs for separator-free date parsing.
+      # Each pair +[a, b]+ divides the token into three parts: +[0...a]+, +[a...b]+, +[b..]+.
+      # Mirrors +DATE_SPLITS+ in the JS v4 source.
+      DATE_SPLITS = {
+        4 => [[1, 2], [2, 3]],
+        5 => [[1, 3], [2, 3]],
+        6 => [[1, 2], [2, 4], [4, 5]],
+        7 => [[1, 3], [2, 3], [4, 5], [4, 6]],
+        8 => [[2, 4], [4, 6]]
+      }.freeze
+
+      # Earliest year accepted as a valid date year.
+      DATE_MIN_YEAR = 1000
+
+      # Latest year accepted as a valid date year.
+      DATE_MAX_YEAR = 2050
+
+      # Returns all date matches found in +password+, deduplicating any match
+      # whose character span is fully contained within another match's span.
+      #
+      # @param password [String] the password to search
+      # @param reference_year [Integer] year used to pick the closest candidate for
+      #   separator-free dates; defaults to the current year
+      # @return [Array<MatchBuilder>] matches with pattern 'date', each containing
+      #   +year+, +month+, +day+, and +separator+
+      def matches(password, reference_year: Time.now.year)
+        all = match_with_separator(password) + match_without_separator(password, reference_year:)
+        all.reject do |match|
+          all.any? { |other| !other.equal?(match) && other.i <= match.i && other.j >= match.j }
+        end
       end
 
+      # Finds date matches that use a separator character (space, slash, hyphen, etc.).
+      # Iterates over all substrings of length 6–10 and tests each against
+      # {MAYBE_DATE_WITH_SEP}, then resolves day/month/year via {map_ints_to_dmy}.
+      #
+      # @param password [String] the password to search
+      # @return [Array<MatchBuilder>] separator-based date matches
       def match_with_separator(password)
         result = []
-        re_match_all(YEAR_SUFFIX, password) do |match, re_match|
-          match.pattern = 'date'
-          match.separator = re_match[2]
-          match.year = re_match[4].to_i
-
-          day = re_match[1].to_i
-          month = re_match[3].to_i
-
-          if month <= 12
-            match.day = day
-            match.month = month
-          else
-            match.day = month
-            match.month = day
+        return result if password.length < 6
+
+        (0..(password.length - 6)).each do |i|
+          ((i + 5)..[i + 9, password.length - 1].min).each do |j|
+            token = password[i..j]
+            m = MAYBE_DATE_WITH_SEP.match(token)
+            next unless m
+
+            date = map_ints_to_dmy(m[1].to_i, m[3].to_i, m[4].to_i)
+            next unless date
+
+            result << MatchBuilder.new(
+              i:, j:, token:,
+              pattern: 'date',
+              separator: m[2],
+              year: date[:year],
+              month: date[:month],
+              day: date[:day]
+            )
           end
-
-          result << match if valid_date?(match.day, match.month, match.year)
         end
         result
       end
 
-      def match_without_separator(password)
+      # Finds date matches in runs of digits that contain no separator character.
+      # Iterates over all digit-only substrings of length 4–8, applies {DATE_SPLITS}
+      # to generate day/month/year candidates via {map_ints_to_dmy}, and picks the
+      # candidate whose year is closest to the current year.
+      #
+      # 4-digit tokens that look like standalone years (matched by {Year::YEAR_REGEX})
+      # are skipped to avoid treating a year token as a date.
+      #
+      # @param password [String] the password to search
+      # @param reference_year [Integer] year used to pick the closest candidate;
+      #   defaults to the current year
+      # @return [Array<MatchBuilder>] separator-free date matches
+      def match_without_separator(password, reference_year: Time.now.year)
         result = []
-        re_match_all(WITHOUT_SEPARATOR, password) do |match, _re_match|
-          extract_dates(match.token).each do |candidate|
-            day = candidate[:day]
-            month = candidate[:month]
-            year = candidate[:year]
-
-            match.pattern = 'date'
-            match.day = day
-            match.month = month
-            match.year = year
-            match.separator = ''
-            result << match
+        return result if password.length < 4
+
+        (0..(password.length - 4)).each do |i|
+          ((i + 3)..[i + 7, password.length - 1].min).each do |j|
+            token = password[i..j]
+            next unless MAYBE_DATE_WITHOUT_SEP.match?(token)
+
+            splits = DATE_SPLITS[token.length]
+            next unless splits
+            next if token.length == 4 && Year::YEAR_REGEX.match?(token)
+
+            candidates = splits.filter_map do |a, b|
+              map_ints_to_dmy(token[0...a].to_i, token[a...b].to_i, token[b..].to_i)
+            end
+            next if candidates.empty?
+
+            best = candidates.min_by { |c| (c[:year] - reference_year).abs }
+
+            result << MatchBuilder.new(
+              i:, j:, token:,
+              pattern: 'date',
+              separator: '',
+              year: best[:year],
+              month: best[:month],
+              day: best[:day]
+            )
           end
         end
         result
       end
 
-      def extract_dates(token)
-        dates = []
-        date_patterns_for_length(token.length).map do |pattern|
-          candidate = {
-            year: +'',
-            month: +'',
-            day: +''
-          }
-          (0...token.length).each do |i|
-            candidate[PATTERN_CHAR_TO_SYM[pattern[i]]] << token[i]
-          end
-          candidate.each do |component, value|
-            candidate[component] = value.to_i
-          end
-
-          candidate[:year] = expand_year(candidate[:year])
-
-          if valid_date?(candidate[:day], candidate[:month], candidate[:year]) && !matches_year?(token)
-            dates << candidate
-          end
+      # Resolves three integers into a +{year:, month:, day:}+ hash, or +nil+ if
+      # no valid assignment exists. Mirrors +map_ints_to_dmy+ in the JS v4 source.
+      #
+      # The middle value (+int2+) is always treated as the non-year component (it
+      # comes from the +\d{1,2}+ capture group in the separator regex, or the
+      # middle split in the no-separator path). The outer two values are tried as
+      # the year: first +int3+, then +int1+. A value in +[DATE_MIN_YEAR, DATE_MAX_YEAR]+
+      # is treated as a 4-digit year (takes priority); otherwise both are tried as
+      # 2-digit years via {expand_year}.
+      #
+      # @param int1 [Integer] first integer (leading digits)
+      # @param int2 [Integer] middle integer (always the non-year component)
+      # @param int3 [Integer] last integer (trailing digits)
+      # @return [Hash, nil] +{year:, month:, day:}+ or +nil+ if no valid date
+      def map_ints_to_dmy(int1, int2, int3)
+        return nil if int2 > 31 || int2 <= 0
+
+        [int1, int2, int3].each do |n|
+          return nil if n > 99 && n < DATE_MIN_YEAR
+          return nil if n > DATE_MAX_YEAR
         end
-        dates
-      end
 
-      DATE_PATTERN_FOR_LENGTH = {
-        8 => %w[yyyymmdd ddmmyyyy mmddyyyy].freeze,
-        7 => %w[yyyymdd yyyymmd ddmyyyy dmmyyyy].freeze,
-        6 => %w[yymmdd ddmmyy mmddyy].freeze,
-        5 => %w[yymdd yymmd ddmyy dmmyy mmdyy mddyy].freeze,
-        4 => %w[yymd dmyy mdyy].freeze
-      }.freeze
+        num_over_thirty_one = [int1, int2, int3].count { |n| n > 31 }
+        num_over_twelve     = [int1, int2, int3].count { |n| n > 12 }
+        num_under_one       = [int1, int2, int3].count { |n| n <= 0 }
+        return nil if num_over_thirty_one >= 2 || num_over_twelve == 3 || num_under_one >= 2
+
+        # Try int3 then int1 as the year; 4-digit range takes priority over 2-digit.
+        # If a 4-digit candidate is found but day/month are invalid, return nil immediately
+        # rather than falling through to the 2-digit pass.
+        pairs = [[int3, int1, int2], [int1, int2, int3]]
+        four_digit = pairs.find { |yc, _dm1, _dm2| yc.between?(DATE_MIN_YEAR, DATE_MAX_YEAR) }
+        if four_digit
+          year_candidate, dm1, dm2 = four_digit
+          dm = map_ints_to_dm(dm1, dm2)
+          return dm ? { year: year_candidate, month: dm[:month], day: dm[:day] } : nil
+        end
 
-      PATTERN_CHAR_TO_SYM = {
-        'y' => :year,
-        'm' => :month,
-        'd' => :day
-      }.freeze
+        # Fall back to 2-digit year
+        pairs.each do |year_candidate, dm1, dm2|
+          dm = map_ints_to_dm(dm1, dm2)
+          next unless dm
 
-      def date_patterns_for_length(length)
-        DATE_PATTERN_FOR_LENGTH[length] || []
-      end
-
-      def valid_date?(day, month, year)
-        return false if day > 31 || month > 12
-        return false unless year >= 1900 && year <= 2019
+          return { year: expand_year(year_candidate), month: dm[:month], day: dm[:day] }
+        end
 
-        true
+        nil
       end
 
-      def matches_year?(token)
-        token.size == 4 && Year::YEAR_REGEX.match(token)
+      # Tries to assign two integers to day and month. Attempts both orderings
+      # and returns the first that satisfies +1 ≤ day ≤ 31+ and +1 ≤ month ≤ 12+.
+      # Mirrors +map_ints_to_dm+ in the JS v4 source.
+      #
+      # @param day_val [Integer] candidate day value
+      # @param month_val [Integer] candidate month value
+      # @return [Hash, nil] +{day:, month:}+ or +nil+ if neither ordering is valid
+      def map_ints_to_dm(day_val, month_val)
+        [[day_val, month_val], [month_val, day_val]].each do |day, month|
+          return { day:, month: } if day.between?(1, 31) && month >= 1 && month <= 12
+        end
+        nil
       end
 
+      # Expands a 2-digit year to 4 digits. Values above 99 are returned unchanged.
+      # Mirrors +two_to_four_digit_year+ in the JS v4 source.
+      #
+      # Threshold is strictly +> 50+, matching JS: 50 → 2050, 51 → 1951.
+      # Negative values are treated as 1900s (e.g. -5 → 1995) — this is an
+      # edge case inherited from the JS implementation.
+      #
+      # @param year [Integer] the year value to expand
+      # @return [Integer] 4-digit year
       def expand_year(year)
-        year
-        # Block dates with 2 digit years for now to be compatible with the JS version
-        # return year unless year < 100
-        # now = Time.now.year
-        # if year <= 19
-        #   year + 2000
-        # else
-        #   year + 1900
-        # end
+        return year if year > 99
+
+        year > 50 ? year + 1900 : year + 2000
       end
     end
   end