zxcvbn-ruby 1.2.4 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52ddbaaabcb2929e59d34d91104bce81b86f223428001218872294363d79f2ac
-  data.tar.gz: 5c488ab8d0dfbd6c46b2b5b05f3b878355e09babe09304c3653c9e45dcf64d02
+  metadata.gz: 36aa566fe4268e91239c2232628e3eb7397cdf06c99608efa63670842a5b5b4c
+  data.tar.gz: 8c736d0a2f84507600e9ba3da51a368f056c2e8918672238415f636bffcd6ca3
 SHA512:
-  metadata.gz: 6ac904b4f3e4219981def358d1f7aa69870e9e33605c3696123e95f936d4880b39d2b5e1d5f323fd89ebc7b2ff43eaa93f22c598ac40ea20bdd768072a082162
-  data.tar.gz: f32d688a3ee53867c1f47f0e52527d3da4397e26c93854305ee5cbcf224e9dad104f087ab80174848b3765dd41a086a6fd33a4ab72a1b72d8ea05209aa88b289
+  metadata.gz: f569dc2cee3a3eee7c8b1adad5f924d74c0b5d2aac11eb61ec4e3330f3043f89d5543a74f073b508b0820bde71e0473b7e096c4d10138fb459fd90dcd7461667
+  data.tar.gz: f5873e8cdf377c6e30097025c5e8b3c02a4a8c65da2fd2051ef14791ee0123a8224e1c1627a0559338e1e16aa6808e1691afd3d00515057ba79732c62737247a

data/CHANGELOG.md

@@ -6,7 +6,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-[Unreleased]: https://github.com/envato/zxcvbn-ruby/compare/v1.2.4...HEAD
+[Unreleased]: https://github.com/envato/zxcvbn-ruby/compare/v1.3.0...HEAD
+
+## [1.3.0] - 2026-01-02
+
+### Changed
+ - Replace OpenStruct with regular class in `Zxcvbn::Match` for 2x performance improvement ([#61])
+ - Implement Trie data structure for dictionary matching with 1.4x additional performance improvement ([#62])
+ - Replace range operators with `String#slice` for string slicing operations ([#63])
+ - Optimise L33t matcher with early bailout and improved deduplication ([#64])
+ - Pre-compute spatial graph statistics during data initialisation ([#65])
+ - Optimise nCk calculation using symmetry property ([#66])
+
+Overall performance improvement: 4.1x faster than v1.2.4 (0.722ms → 0.176ms per password)
+
+[1.3.0]: https://github.com/envato/zxcvbn-ruby/compare/v1.2.4...v1.3.0
+[#61]: https://github.com/envato/zxcvbn-ruby/pull/61
+[#62]: https://github.com/envato/zxcvbn-ruby/pull/62
+[#63]: https://github.com/envato/zxcvbn-ruby/pull/63
+[#64]: https://github.com/envato/zxcvbn-ruby/pull/64
+[#65]: https://github.com/envato/zxcvbn-ruby/pull/65
+[#66]: https://github.com/envato/zxcvbn-ruby/pull/66
 
 ## [1.2.4] - 2025-12-07
 

data/lib/zxcvbn/data.rb

@@ -2,6 +2,7 @@
 
 require 'json'
 require 'zxcvbn/dictionary_ranker'
+require 'zxcvbn/trie'
 
 module Zxcvbn
   class Data
@@ -14,12 +15,16 @@ module Zxcvbn
         'surnames' => read_word_list('surnames.txt')
       )
       @adjacency_graphs = JSON.parse(DATA_PATH.join('adjacency_graphs.json').read)
+      @dictionary_tries = build_tries
+      @graph_stats = compute_graph_stats
     end
 
-    attr_reader :ranked_dictionaries, :adjacency_graphs
+    attr_reader :ranked_dictionaries, :adjacency_graphs, :dictionary_tries, :graph_stats
 
     def add_word_list(name, list)
-      @ranked_dictionaries[name] = DictionaryRanker.rank_dictionary(list)
+      ranked_dict = DictionaryRanker.rank_dictionary(list)
+      @ranked_dictionaries[name] = ranked_dict
+      @dictionary_tries[name] = build_trie(ranked_dict)
     end
 
     private
@@ -27,5 +32,31 @@ module Zxcvbn
     def read_word_list(file)
       DATA_PATH.join('frequency_lists', file).read.split
     end
+
+    def build_tries
+      @ranked_dictionaries.transform_values { |dict| build_trie(dict) }
+    end
+
+    def build_trie(ranked_dictionary)
+      trie = Trie.new
+      ranked_dictionary.each { |word, rank| trie.insert(word, rank) }
+      trie
+    end
+
+    def compute_graph_stats
+      stats = {}
+      @adjacency_graphs.each do |graph_name, graph|
+        degrees = graph.map { |_, neighbors| neighbors.compact.size }
+        sum = degrees.inject(0, :+)
+        average_degree = sum.to_f / graph.size
+        starting_positions = graph.length
+
+        stats[graph_name] = {
+          average_degree: average_degree,
+          starting_positions: starting_positions
+        }
+      end
+      stats
+    end
   end
 end

data/lib/zxcvbn/dictionary_ranker.rb

@@ -9,10 +9,9 @@ module Zxcvbn
     end
 
     def self.rank_dictionary(words)
-      words.each_with_index
-           .with_object({}) do |(word, i), dictionary|
-        dictionary[word.downcase] = i + 1
-      end
+      words
+        .each_with_index
+        .with_object({}) { |(word, i), dictionary| dictionary[word.downcase] = i + 1 }
     end
   end
 end

data/lib/zxcvbn/match.rb

@@ -1,12 +1,24 @@
 # frozen_string_literal: true
 
-require 'ostruct'
-
 module Zxcvbn
-  class Match < OpenStruct
+  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
+
+    def initialize(**attributes)
+      attributes.each do |key, value|
+        instance_variable_set("@#{key}", value)
+      end
+    end
+
     def to_hash
-      @table.keys.sort.each_with_object({}) do |key, hash|
-        hash[key.to_s] = @table[key]
+      instance_variables.sort.each_with_object({}) do |var, hash|
+        key = var.to_s.delete_prefix('@')
+        hash[key] = instance_variable_get(var)
       end
     end
   end

data/lib/zxcvbn/matchers/dictionary.rb

@@ -8,33 +8,64 @@ module Zxcvbn
     # the lowercased password in the dictionary
 
     class Dictionary
-      def initialize(name, ranked_dictionary)
+      def initialize(name, ranked_dictionary, trie = nil)
         @name = name
         @ranked_dictionary = ranked_dictionary
+        @trie = trie
       end
 
       def matches(password)
+        lowercased_password = password.downcase
+
+        if @trie
+          trie_matches(password, lowercased_password)
+        else
+          hash_matches(password, lowercased_password)
+        end
+      end
+
+      private
+
+      def trie_matches(password, lowercased_password)
+        results = []
+
+        (0...password.length).each do |i|
+          @trie.search_prefixes(lowercased_password, i).each do |word, rank, start, ending|
+            results << build_match(word, password.slice(start, ending - start + 1), start, ending, rank)
+          end
+        end
+
+        results
+      end
+
+      def hash_matches(password, lowercased_password)
         results = []
         password_length = password.length
-        lowercased_password = password.downcase
+
         (0..password_length).each do |i|
           (i...password_length).each do |j|
-            word = lowercased_password[i..j]
+            length = j - i + 1
+            word = lowercased_password.slice(i, length)
             next unless @ranked_dictionary.key?(word)
 
-            results << Match.new(
-              matched_word: word,
-              token: password[i..j],
-              i: i,
-              j: j,
-              rank: @ranked_dictionary[word],
-              pattern: 'dictionary',
-              dictionary_name: @name
-            )
+            results << build_match(word, password.slice(i, length), i, j, @ranked_dictionary[word])
           end
         end
+
         results
       end
+
+      def build_match(matched_word, token, start_pos, end_pos, rank)
+        Match.new(
+          matched_word: matched_word,
+          token: token,
+          i: start_pos,
+          j: end_pos,
+          rank: rank,
+          pattern: 'dictionary',
+          dictionary_name: @name
+        )
+      end
     end
   end
 end

data/lib/zxcvbn/matchers/l33t.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'set'
+
 module Zxcvbn
   module Matchers
     class L33t
@@ -25,25 +27,17 @@ module Zxcvbn
       def matches(password)
         matches = []
         lowercased_password = password.downcase
-        combinations_to_try = l33t_subs(relevent_l33t_subtable(lowercased_password))
+        relevent_subtable = relevent_l33t_subtable(lowercased_password)
+
+        # Early bailout: if no l33t characters present, return empty matches
+        return matches if relevent_subtable.empty?
+
+        combinations_to_try = l33t_subs(relevent_subtable)
         combinations_to_try.each do |substitution|
           @dictionary_matchers.each do |matcher|
             subbed_password = translate(lowercased_password, substitution)
             matcher.matches(subbed_password).each do |match|
-              token = password[match.i..match.j]
-              next if token.downcase == match.matched_word.downcase
-
-              match_substitutions = {}
-              substitution.each do |s, letter|
-                match_substitutions[s] = letter if token.include?(s)
-              end
-              match.l33t = true
-              match.token = password[match.i..match.j]
-              match.sub = match_substitutions
-              match.sub_display = match_substitutions.map do |k, v|
-                "#{k} -> #{v}"
-              end.join(', ')
-              matches << match
+              process_match(match, password, substitution, matches)
             end
           end
         end
@@ -51,9 +45,11 @@ module Zxcvbn
       end
 
       def translate(password, sub)
-        password.split('').map do |chr|
-          sub[chr] || chr
-        end.join
+        result = String.new
+        password.each_char do |chr|
+          result << (sub[chr] || chr)
+        end
+        result
       end
 
       def relevent_l33t_subtable(password)
@@ -80,6 +76,26 @@ module Zxcvbn
         new_subs
       end
 
+      private
+
+      def process_match(match, password, substitution, matches)
+        length = match.j - match.i + 1
+        token = password.slice(match.i, length)
+        return if token.downcase == match.matched_word.downcase
+
+        match_substitutions = {}
+        substitution.each do |s, letter|
+          match_substitutions[s] = letter if token.include?(s)
+        end
+        match.l33t = true
+        match.token = token
+        match.sub = match_substitutions
+        match.sub_display = match_substitutions.map do |k, v|
+          "#{k} -> #{v}"
+        end.join(', ')
+        matches << match
+      end
+
       def find_substitutions(subs, table, keys)
         return subs if keys.empty?
 
@@ -113,14 +129,12 @@ module Zxcvbn
 
       def dedup(subs)
         deduped = []
-        members = []
+        seen = Set.new
         subs.each do |sub|
-          assoc = sub.dup
-
-          assoc.sort!
-          label = assoc.map { |k, v| "#{k},#{v}" }.join('-')
-          unless members.include?(label)
-            members << label
+          # Sort and convert to hash for consistent comparison
+          sorted_sub = sub.sort.to_h
+          unless seen.include?(sorted_sub)
+            seen.add(sorted_sub)
             deduped << sub
           end
         end

data/lib/zxcvbn/matchers/new_l33t.rb

@@ -30,7 +30,8 @@ module Zxcvbn
           @dictionary_matchers.each do |matcher|
             subbed_password = substitute(lowercased_password, substitutions)
             matcher.matches(subbed_password).each do |match|
-              token = lowercased_password[match.i..match.j]
+              length = match.j - match.i + 1
+              token = lowercased_password.slice(match.i, length)
               next if token == match.matched_word.downcase
 
               match_substitutions = {}
@@ -38,7 +39,7 @@ module Zxcvbn
                 match_substitutions[substitution] = letter if token.include?(substitution)
               end
               match.l33t = true
-              match.token = password[match.i..match.j]
+              match.token = password.slice(match.i, length)
               match.sub = match_substitutions
               match.sub_display = match_substitutions.map do |k, v|
                 "#{k} -> #{v}"

data/lib/zxcvbn/matchers/regex_helpers.rb

@@ -15,7 +15,7 @@ module Zxcvbn
           match = Match.new(
             i: i,
             j: j,
-            token: password[i..j]
+            token: password.slice(i, j - i + 1)
           )
           yield match, re_match
         end

data/lib/zxcvbn/matchers/repeat.rb

@@ -18,7 +18,7 @@ module Zxcvbn
               pattern: 'repeat',
               i: i,
               j: j - 1,
-              token: password[i...j],
+              token: password.slice(i, j - i),
               repeated_char: cur_char
             )
           end

data/lib/zxcvbn/matchers/spatial.rb

@@ -64,7 +64,7 @@ module Zxcvbn
                   pattern: 'spatial',
                   i: i,
                   j: j - 1,
-                  token: password[i...j],
+                  token: password.slice(i, j - i),
                   graph: graph_name,
                   turns: turns,
                   shifted_count: shifted_count

data/lib/zxcvbn/math.rb

@@ -34,6 +34,10 @@ module Zxcvbn
       return 0 if k > n
       return 1 if k.zero?
 
+      # Use symmetry property: C(n,k) = C(n, n-k)
+      # Choose smaller k to minimize iterations
+      k = n - k if k > n - k
+
       r = 1
       (1..k).each do |d|
         r *= n
@@ -44,14 +48,11 @@ module Zxcvbn
     end
 
     def average_degree_for_graph(graph_name)
-      graph = data.adjacency_graphs[graph_name]
-      degrees = graph.map { |_, neighbors| neighbors.compact.size }
-      sum = degrees.inject(0, :+)
-      sum.to_f / graph.size
+      data.graph_stats[graph_name][:average_degree]
     end
 
     def starting_positions_for_graph(graph_name)
-      data.adjacency_graphs[graph_name].length
+      data.graph_stats[graph_name][:starting_positions]
     end
   end
 end

data/lib/zxcvbn/omnimatch.rb

@@ -38,7 +38,8 @@ module Zxcvbn
     def build_matchers
       matchers = []
       dictionary_matchers = @data.ranked_dictionaries.map do |name, dictionary|
-        Matchers::Dictionary.new(name, dictionary)
+        trie = @data.dictionary_tries[name]
+        Matchers::Dictionary.new(name, dictionary, trie)
       end
       l33t_matcher = Matchers::L33t.new(dictionary_matchers)
       matchers += dictionary_matchers

data/lib/zxcvbn/scorer.rb

@@ -96,7 +96,7 @@ module Zxcvbn
         pattern: 'bruteforce',
         i: i,
         j: j,
-        token: password[i..j],
+        token: password.slice(i, j - i + 1),
         entropy: lg(bruteforce_cardinality**(j - i + 1)),
         cardinality: bruteforce_cardinality
       )

data/lib/zxcvbn/trie.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Zxcvbn
+  # A trie (prefix tree) data structure for efficient dictionary matching.
+  # Provides fast prefix-based lookups to eliminate unnecessary substring checks.
+  #
+  # @see https://en.wikipedia.org/wiki/Trie
+  class Trie
+    def initialize
+      @root = {}
+    end
+
+    # Insert a word and its rank into the trie
+    # @param word [String] the word to insert
+    # @param rank [Integer] the rank/frequency of the word
+    def insert(word, rank)
+      node = @root
+      word.each_char do |char|
+        node[char] ||= {}
+        node = node[char]
+      end
+      node[:rank] = rank
+    end
+
+    # Search for all words in the text starting from a given position
+    # @param text [String] the text to search in
+    # @param start_pos [Integer] the starting position
+    # @return [Array<Array>] array of [word, rank, start, end] tuples
+    def search_prefixes(text, start_pos)
+      results = []
+      node = @root
+
+      (start_pos...text.length).each do |i|
+        char = text[i]
+        break unless node[char]
+
+        node = node[char]
+        results << [text[start_pos..i], node[:rank], start_pos, i] if node[:rank]
+      end
+
+      results
+    end
+  end
+end

data/lib/zxcvbn/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Zxcvbn
-  VERSION = '1.2.4'
+  VERSION = '1.3.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zxcvbn-ruby
 version: !ruby/object:Gem::Version
-  version: 1.2.4
+  version: 1.3.0
 platform: ruby
 authors:
 - Steve Hodgkiss
@@ -52,6 +52,7 @@ files:
 - lib/zxcvbn/score.rb
 - lib/zxcvbn/scorer.rb
 - lib/zxcvbn/tester.rb
+- lib/zxcvbn/trie.rb
 - lib/zxcvbn/version.rb
 homepage: http://github.com/envato/zxcvbn-ruby
 licenses:
@@ -76,7 +77,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.0
+rubygems_version: 4.0.3
 specification_version: 4
 summary: ''
 test_files: []