rambling-trie 2.6.0 → 2.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52fe8e610cf15d433a18cbb24cdd4b72c48a4ab50398868ab68cce58ea0a8de6
-  data.tar.gz: a106639989c7ad33230c252d470a9c7924fd65204ab633743bd813d4f69fa4d4
+  metadata.gz: 3a9d76d13a38a54c80ca90236346dcfe280fea62d46d8e9318efc8f2653b6f40
+  data.tar.gz: 0ab262b5f456d0e299fc16614bb0c7103406899b0a88dce3ef69d0d1f403fd3c
 SHA512:
-  metadata.gz: 6d4659cf7e712e4fbed4e6054d6f27f7db0ecbf4dca13fcad6cab34c3050b78cb63cee7993ccda2146868b8d7203932bea08667bb510d0afdcada8cb403c3418
-  data.tar.gz: a36621b0ee84dbb8905ca8af25b8fc1b2b08a23ce171fb83c3ec632f39ffc1e7108828330eb93c4285948e5c32a1a6c6d116ad74d9da5a28aa9bd428110dafe5
+  metadata.gz: 13ccb7f63311ae91544442fe75e1620ecb91ef87501150fa46f454f80b7b4d51cda69ebeb8c82e474173db815e5f536b9cf03cccb3fa8e6233facfbd7f265949
+  data.tar.gz: dfab4eaea2613f6ad5957579089056441d3f01533112fff081504da2be2e18f77267350f6cedd4c61d65d88075cf0e83d22e5124370fac45fa2dadc36b22ddcb

data/Dockerfile

@@ -1,4 +1,5 @@
-FROM ruby:3.3.6
+ARG RUBY_VERSION=3.3.6
+FROM ruby:${RUBY_VERSION}
 
 RUN bundle config --global frozen 1
 

data/README.md

@@ -299,7 +299,7 @@ The Rambling Trie has been tested with the following Ruby versions:
 
 ## Compatible RBS and Steep versions
 
-Type signatures for `Rambling::Trie` are included in the [`sig` directory](./sig)! The current version (`2.6.0`) was
+Type signatures for `Rambling::Trie` are included in the [`sig` directory](./sig)! The current version (`2.7.0`) was
 checked with RBS `3.10.4` and Steep `1.10.0`.
 
 ## Contributing to Rambling Trie
@@ -327,7 +327,7 @@ COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER I
 OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 [asdf]: https://asdf-vm.com/
-[badge_fury_badge]: https://badge.fury.io/rb/rambling-trie.svg?version=2.6.0
+[badge_fury_badge]: https://badge.fury.io/rb/rambling-trie.svg?version=2.7.0
 [badge_fury_link]: https://badge.fury.io/rb/rambling-trie
 [chruby]: https://github.com/postmodern/chruby
 [code_climate_grade_badge]: https://codeclimate.com/github/gonzedge/rambling-trie/badges/gpa.svg

data/Steepfile

@@ -13,9 +13,13 @@ target :lib do
   # check 'Rakefile'
   # check 'Steepfile'
 
-  # library 'rubyzip'
+  collection_config 'rbs_collection.yaml'
+
+  library 'rubyzip'
+  library 'rake'
   library 'yaml'
   library 'securerandom'
+  library 'tmpdir'
 
   # configure_code_diagnostics(D::Ruby.default)      # `default` diagnostics setting (applies by default)
   # configure_code_diagnostics(D::Ruby.strict)       # `strict` diagnostics setting

data/lib/rambling/trie/comparable.rb

@@ -6,11 +6,13 @@ module Rambling
     module Comparable
       # Compares two nodes.
       # @param [Nodes::Node] other the node to compare against.
-      # @return [Boolean] `true` if the nodes' {Nodes::Node#letter #letter} and
-      #   {Nodes::Node#children_tree #children_tree} are equal, `false` otherwise.
+      # @return [Boolean] `true` if the nodes' {Nodes::Node#letter #letter},
+      #   {Nodes::Node#terminal? #terminal?}, {Nodes::Node#value #value}, and
+      #   {Nodes::Node#children_tree #children_tree} are all equal, `false` otherwise.
       def == other
         letter == other.letter &&
           terminal? == other.terminal? &&
+          value == other.value &&
           children_tree == other.children_tree
       end
     end

data/lib/rambling/trie/compressible.rb

@@ -7,7 +7,7 @@ module Rambling
       # Indicates if the current {Rambling::Trie::Nodes::Node Node} can be compressed or not.
       # @return [Boolean] `true` for non-{Nodes::Node#terminal? terminal} nodes with one child, `false` otherwise.
       def compressible?
-        !(root? || terminal?) && 1 == children_tree.size
+        !root? && !terminal? && children_tree.one?
       end
     end
   end

data/lib/rambling/trie/compressor.rb

@@ -37,7 +37,7 @@ module Rambling
         if other.terminal?
           compressed.terminal!
           value = other.value
-          compressed.value = value if value
+          compressed.value = value unless value.nil?
         end
         compressed
       end
@@ -48,7 +48,7 @@ module Rambling
         if node.terminal?
           compressed.terminal!
           value = node.value
-          compressed.value = value if value
+          compressed.value = value unless value.nil?
         end
         compressed
       end

data/lib/rambling/trie/configuration/properties.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'tmpdir'
+
 module Rambling
   module Trie
     module Configuration
@@ -39,7 +41,7 @@ module Rambling
 
           @compressor = Rambling::Trie::Compressor.new
           @root_builder = -> { Rambling::Trie::Nodes::Raw.new }
-          @tmp_path = '/tmp'
+          @tmp_path = Dir.tmpdir
         end
 
         private

data/lib/rambling/trie/configuration/provider_collection.rb

@@ -17,7 +17,6 @@ module Rambling
         #   providers.
         #   @param [TProvider] provider the provider to use as default.
         #   @raise [ArgumentError] when the given provider is not in the provider collection.
-        #   @note If no providers have been configured, `nil` will be assigned.
         # @return [TProvider, nil] the default provider to use when a provider cannot be resolved in
         #   {ProviderCollection#resolve #resolve}.
         attr_reader :default
@@ -25,7 +24,8 @@ module Rambling
         # Creates a new provider collection.
         # @param [Symbol] name the name for this provider collection.
         # @param [Hash<Symbol, TProvider>] providers the configured providers.
-        # @param [TProvider, nil] default the configured default provider.
+        # @param [TProvider, nil] default the configured default provider. When +nil+ (or no providers
+        #   are given), falls back to the first configured provider, or +nil+ if none exist.
         def initialize name, providers = {}, default = nil
           @name = name
           @configured_providers = providers
@@ -74,9 +74,9 @@ module Rambling
           self.default = configured_default
         end
 
-        # Get provider corresponding to a given format.
-        # @return [Array<Symbol>] the provider corresponding to that format.
-        # @see https://ruby-doc.org/3.3.0/Hash.html#method-i-5B-5D
+        # List the formats of configured providers.
+        # @return [Array<Symbol>] the formats of all configured providers.
+        # @see https://ruby-doc.org/3.3.0/Hash.html#method-i-keys
         #   Hash#keys
         def formats
           providers.keys
@@ -84,7 +84,7 @@ module Rambling
 
         # Get provider corresponding to a given format.
         # @param [Symbol] format the format to search for in the collection.
-        # @return [TProvider] the provider corresponding to that format.
+        # @return [TProvider, nil] the provider corresponding to that format, or +nil+ if not found.
         # @see https://ruby-doc.org/3.3.0/Hash.html#method-i-5B-5D Hash#[]
         def [] format
           providers[format]
@@ -109,7 +109,7 @@ module Rambling
         def contains? provider
           return true if provider.nil?
 
-          providers.any? && provider_instances.include?(provider || raise)
+          provider_instances.include?(provider || raise)
         end
 
         alias_method :provider_instances, :values

data/lib/rambling/trie/container.rb

@@ -22,7 +22,8 @@ module Rambling
       end
 
       # Adds a word to the trie.
-      # @param [String] word the word to add the branch from.
+      # @param [String] word the word to add to the trie.
+      # @param [Object, nil] value the value to associate with the word.
       # @return [Nodes::Node] the just added branch's root node.
       # @raise [InvalidOperation] if the trie is already compressed.
       # @see Nodes::Raw#add
@@ -32,13 +33,22 @@ module Rambling
       end
 
       # Adds all provided words to the trie.
-      # @param [Array<String>] words the words to add the branch from.
+      # @param [Array<String>] words the words to add to the trie.
+      # @param [Array<Object>, nil] values the values to associate with each word, in the same order.
       # @return [Array<Nodes::Node>] the collection of nodes added.
       # @raise [InvalidOperation] if the trie is already compressed.
+      # @raise [ArgumentError] if words and values are given but differ in size.
       # @see Nodes::Raw#add
       # @see Nodes::Compressed#add
       def concat words, values = nil
         if values
+          words_size = words.size
+          values_size = values.size
+          unless words_size == values_size
+            raise ArgumentError,
+              "words and values must have the same size (words: #{words_size}, values: #{values_size})"
+          end
+
           words.each_with_index.map { |word, index| add(word, values[index]) }
         else
           words.map { |word| add word }
@@ -56,10 +66,18 @@ module Rambling
       end
 
       # Compresses the existing trie using redundant node elimination. Returns a new trie with the compressed root.
-      # @return [Container] A new {Container} with the {Nodes::Compressed Compressed} root node
-      #   or self if the trie has already been compressed.
+      # @return [Container] A new {Container} with the {Nodes::Compressed Compressed} root node.
+      # @deprecated Calling {#compress} on an already-compressed trie is deprecated and will raise
+      #   {InvalidOperation} in the next major version. Use {#compressed?} to guard if needed.
       def compress
-        return self if root.compressed?
+        if root.compressed?
+          warn <<~WARN.chomp.tr("\n", ' ')
+            [DEPRECATED] Calling `compress` on an already-compressed trie is deprecated
+            and will raise `InvalidOperation` in the next major version.
+            Called from #{caller_locations(1, 1)&.first}
+          WARN
+          return Rambling::Trie::Container.new root, compressor
+        end
 
         Rambling::Trie::Container.new compress_root, compressor
       end
@@ -73,7 +91,7 @@ module Rambling
       end
 
       # Adds all provided words to the trie.
-      # @param [Array<String>] words the words to add the branch from.
+      # @param [String] words the words to add to the trie.
       # @return [Array<Nodes::Node>] the collection of nodes added.
       # @raise [InvalidOperation] if the trie is already compressed.
       # @see #concat
@@ -103,7 +121,6 @@ module Rambling
       # Returns all words within a string that match a word contained in the trie.
       # @param [String] phrase the string to look for matching words in.
       # @return [Array<String>] all the words in the given string that match a word in the trie.
-      # @yield [String] each word found in phrase.
       def words_within phrase
         words_within_root(phrase).to_a
       end
@@ -130,6 +147,8 @@ module Rambling
         return enum_for :each unless block_given?
 
         root.each { |word| yield word }
+
+        self
       end
 
       # @return [String] a string representation of the container.
@@ -181,8 +200,8 @@ module Rambling
         root.key? letter
       end
 
-      # Size of the Root {Nodes::Node Node}'s children tree.
-      # @return [Integer] the number of letters in the root node.
+      # Number of words contained in the trie.
+      # @return [Integer] the number of words stored in the trie.
       def size
         root.size
       end
@@ -203,13 +222,12 @@ module Rambling
         return enum_for :words_within_root, phrase unless block_given?
 
         chars = phrase.chars
-        size = chars.length
-        # rubocop:disable Style/CommentedKeyword
-        0.upto(size - 1).each do |starting_index|
-          new_phrase = chars.slice starting_index, size # : Array[String]
+        chars.each_index do |starting_index|
+          new_phrase = chars[starting_index..] || raise
           root.match_prefix(new_phrase) { |word| yield word }
-        end # : Enumerator[String, void]
-        # rubocop:enable Style/CommentedKeyword
+        end
+
+        self
       end
 
       def compress_root
@@ -217,7 +235,10 @@ module Rambling
       end
 
       def reversed_char_symbols word
-        word.reverse.chars.map(&:to_sym).to_a
+        # @type var chars: Array[String]
+        chars = word.chars
+        chars.reverse!
+        chars.map(&:to_sym)
       end
     end
   end

data/lib/rambling/trie/enumerable.rb

@@ -6,10 +6,6 @@ module Rambling
     module Enumerable
       include ::Enumerable
 
-      # Empty enumerator constant for early each exits.
-      EMPTY_ENUMERATOR = [] # : Array[String]
-                         .to_enum :each
-
       # Returns number of words contained in the trie
       # @see https://ruby-doc.org/3.3.0/Enumerable.html#method-i-count Enumerable#count
       alias_method :size, :count
@@ -26,6 +22,14 @@ module Rambling
 
         self
       end
+
+      # Returns a new empty enumerator for early-exit returns.
+      # A method rather than a constant to prevent shared mutable state.
+      def empty_enum
+        # @type var empty_array: Array[String]
+        empty_array = []
+        empty_array.each
+      end
     end
   end
 end

data/lib/rambling/trie/nodes/compressed.rb

@@ -19,10 +19,10 @@ module Rambling
 
         # Always raises {Rambling::Trie::InvalidOperation InvalidOperation} when
         # trying to add a word to the current compressed trie node
-        # @param [String] _ the word to add to the trie.
-        # @raise [InvalidOperation] if the trie is already compressed.
-        # @return [void]
-        def add _, _ = nil
+        # @param [Array<Symbol>] _word the word chars to add to the trie.
+        # @param [Object, nil] _value the value to associate with the word.
+        # @raise [InvalidOperation] always.
+        def add _word, _value = nil
           raise Rambling::Trie::InvalidOperation, 'Cannot add word to compressed trie'
         end
 
@@ -42,12 +42,12 @@ module Rambling
 
           if chars.size >= child_letter.size
             letter = (chars.shift(child_letter.size) || raise).join
-            return child.partial_word? chars if child_letter == letter
-          end
+            return false unless child_letter == letter
 
-          letter = chars.join
-          child_letter = child_letter.slice 0, letter.size
-          child_letter == letter
+            child.partial_word? chars
+          else
+            child_letter.start_with? chars.join
+          end
         end
 
         def word_chars? chars
@@ -75,29 +75,37 @@ module Rambling
 
           child_letter = child.letter.to_s
 
-          if chars.size >= child_letter.size
-            letter = (chars.shift(child_letter.size) || raise).join
-            return child.scan chars if child_letter == letter
+          if chars.size < child_letter.size
+            return child_letter.start_with?(chars.join) ? child : missing
           end
 
-          letter = chars.join
-          child_letter = child_letter.slice 0, letter.size
+          letter = (chars.shift(child_letter.size) || raise).join
+          return missing unless child_letter == letter
 
-          child_letter == letter ? child : missing
+          child.scan chars
         end
 
         def children_match_prefix chars
           return enum_for :children_match_prefix, chars unless block_given?
 
-          return EMPTY_ENUMERATOR if chars.empty?
+          return empty_enum if chars.empty?
 
           child = children_tree[(chars.first || raise).to_sym]
-          return EMPTY_ENUMERATOR unless child
+          return empty_enum unless child
 
+          match_child_prefix(child, chars) { |word| yield word }
+        end
+
+        def match_child_prefix child, chars
           child_letter = child.letter.to_s
+
+          # stop early if we already know that the remaining characters in the
+          # given phrase do not even cover the current node's compressed key
+          return empty_enum if chars.size < child_letter.size
+
           letter = (chars.shift(child_letter.size) || raise).join
 
-          return EMPTY_ENUMERATOR unless child_letter == letter
+          return empty_enum unless child_letter == letter
 
           child.match_prefix(chars) { |word| yield word }
         end

data/lib/rambling/trie/nodes/missing.rb

@@ -5,6 +5,23 @@ module Rambling
     module Nodes
       # A representation of a missing node in the trie data structure. Returned when a node is not found.
       class Missing < Rambling::Trie::Nodes::Node
+        def partial_word? _
+          false
+        end
+
+        private
+
+        def word_chars? _
+          false
+        end
+
+        def closest_node _
+          self
+        end
+
+        def children_match_prefix chars
+          enum_for :children_match_prefix, chars unless block_given?
+        end
       end
     end
   end

data/lib/rambling/trie/nodes/node.rb

@@ -7,6 +7,7 @@ module Rambling
       # :reek:MissingSafeMethod { exclude: [ terminal! ] }
       # :reek:RepeatedConditional { max_ifs: 3 }
       class Node
+        include NotImplemented
         include Rambling::Trie::Compressible
         include Rambling::Trie::Enumerable
         include Rambling::Trie::Comparable
@@ -32,17 +33,19 @@ module Rambling
         attr_accessor :parent
 
         # Arbitrary value stored in this node
-        # @return [TValue, nil] the parent of the current node.
+        # @return [TValue, nil] the value stored in this node.
         attr_accessor :value
 
         # Creates a new node.
         # @param [Symbol, nil] letter the Node's letter value.
         # @param [Node, nil] parent the parent of the current node.
-        # @param [Hash<Symbol, Node>] children_tree the children tree of the current node.
-        def initialize letter = nil, parent = nil, children_tree = {}
+        # @param [Hash<Symbol, Node>, nil] children_tree the children tree of the current node,
+        #   or +nil+ to start with an empty tree. When a hash is provided, ownership transfers
+        #   to the node; callers must not retain references to or mutate the hash after passing it.
+        def initialize letter = nil, parent = nil, children_tree = nil
           @letter = letter
           @parent = parent
-          @children_tree = children_tree
+          @children_tree = children_tree || {}
         end
 
         # Child nodes.
@@ -54,13 +57,7 @@ module Rambling
         # First child node.
         # @return [Node, nil] the first child contained in the current node.
         def first_child
-          return if children_tree.empty?
-
-          # rubocop:disable Lint/UnreachableLoop
-          children_tree.each_value { |child| return child }
-          # rubocop:enable Lint/UnreachableLoop
-
-          nil
+          children_tree.each_value.first
         end
 
         # Indicates if the current node is the root node.
@@ -137,7 +134,7 @@ module Rambling
         end
 
         # Set the {Node Node} that corresponds to a given letter.
-        # @param [Symbol] letter the letter to insert or update in the node's
+        # @param [Symbol] letter the letter to insert or update in the node's children tree.
         # @param [Node] node the {Node Node} to assign to that letter.
         # @return [Node] the node corresponding to the inserted or updated letter.
         # @see https://ruby-doc.org/3.3.0/Hash.html#method-i-5B-5D Hash#[]
@@ -174,22 +171,28 @@ module Rambling
 
         attr_accessor :terminal
 
-        # abstract methods
-
-        def children_match_prefix chars
-          raise NotImplementedError
+        # @abstract Subclass and override {#children_match_prefix} to match a prefix against child nodes.
+        # @raise [NotImplementedError] when not overridden by a subclass
+        def children_match_prefix _chars
+          not_implemented
         end
 
-        def partial_word_chars? chars
-          raise NotImplementedError
+        # @abstract Subclass and override {#partial_word_chars?} to check for a partial-word path.
+        # @raise [NotImplementedError] when not overridden by a subclass
+        def partial_word_chars? _chars
+          not_implemented
         end
 
-        def word_chars? chars
-          raise NotImplementedError
+        # @abstract Subclass and override {#word_chars?} to check for a full-word path.
+        # @raise [NotImplementedError] when not overridden by a subclass
+        def word_chars? _chars
+          not_implemented
         end
 
-        def closest_node chars
-          raise NotImplementedError
+        # @abstract Subclass and override {#closest_node} to return the deepest matching node.
+        # @raise [NotImplementedError] when not overridden by a subclass
+        def closest_node _chars
+          not_implemented
         end
       end
     end

data/lib/rambling/trie/nodes/raw.rb

@@ -9,7 +9,7 @@ module Rambling
         # Adds a word to the current raw (uncompressed) trie node.
         # @param [Array<Symbol>] reversed_chars the char array to add to the trie, in reverse order.
         # @return [Node] the added/modified node based on the word added.
-        # @note This method clears the contents of the chars variable.
+        # @note This method consumes the array by popping each element during recursion, leaving it empty on return.
         def add reversed_chars, value = nil
           if reversed_chars.empty?
             unless root?
@@ -70,10 +70,10 @@ module Rambling
         def children_match_prefix chars
           return enum_for :children_match_prefix, chars unless block_given?
 
-          return EMPTY_ENUMERATOR if chars.empty?
+          return empty_enum if chars.empty?
 
           child = children_tree[(chars.shift || raise).to_sym]
-          return EMPTY_ENUMERATOR unless child
+          return empty_enum unless child
 
           child.match_prefix(chars) { |word| yield word }
         end

data/lib/rambling/trie/not_implemented.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Rambling
+  # :reek:IrresponsibleModule (unclear why this is necessary here but not in other submodules)
+  module Trie
+    # Provides a private helper for marking abstract methods.
+    # @api private
+    module NotImplemented
+      private
+
+      # Raises {NotImplementedError} with the concrete class and calling method name.
+      # @raise [NotImplementedError] always, with message
+      #   <code>"ClassName#method_name is not implemented"</code>
+      # @return [void]
+      def not_implemented
+        raise NotImplementedError,
+          "#{self.class}##{caller_locations(1, 1)&.first&.label} is not implemented"
+      end
+    end
+
+    private_constant :NotImplemented
+  end
+end

data/lib/rambling/trie/readers/plain_text.rb

@@ -12,7 +12,10 @@ module Rambling
         def each_word filepath
           return enum_for :each_word, filepath unless block_given?
 
-          ::File.foreach(filepath) { |line| yield line.chomp! }
+          ::File.foreach(filepath) do |line|
+            line.chomp!
+            yield line
+          end
 
           self
         end

data/lib/rambling/trie/readers/reader.rb

@@ -5,13 +5,16 @@ module Rambling
     module Readers
       # Base class for all readers.
       class Reader
+        include NotImplemented
+
         # Yields each word read from given file.
         # @abstract Subclass and override {#each_word} to fit to a particular file format.
         # @param [String] filepath the full path of the file to load the words from.
         # @yield [String] Each line read from the file.
         # @return [self]
-        def each_word filepath
-          raise NotImplementedError
+        # @raise [NotImplementedError] when not overridden by a subclass
+        def each_word _filepath
+          not_implemented
         end
       end
     end

data/lib/rambling/trie/serializers/marshal.rb

@@ -19,6 +19,11 @@ module Rambling
         # @note Use of {https://ruby-doc.org/3.3.0/Marshal.html#method-c-load Marshal.load} is generally
         #   discouraged. Only use this with trusted input.
         def load filepath
+          warn <<~WARN.chomp.tr("\n", ' ')
+            WARNING: Marshal.load is being used to deserialize trie data.
+            Loading untrusted input via Marshal.load can execute arbitrary code.
+            Only load Marshal data from trusted sources.
+          WARN
           ::Marshal.load serializer.load filepath
         end
 

data/lib/rambling/trie/serializers/serializer.rb

@@ -5,12 +5,15 @@ module Rambling
     module Serializers
       # Base class for all serializers.
       class Serializer
+        include NotImplemented
+
         # Loads contents from a specified filepath.
         # @abstract Subclass and override {#load} to parse the desired format.
         # @param [String] filepath the filepath to load contents from.
         # @return [TContents] parsed contents from given file.
-        def load filepath
-          raise NotImplementedError
+        # @raise [NotImplementedError] when not overridden by a subclass
+        def load _filepath
+          not_implemented
         end
 
         # Dumps contents into a specified filepath.
@@ -18,8 +21,9 @@ module Rambling
         # @param [TContents] contents the contents to dump into given file.
         # @param [String] filepath the filepath to dump the contents to.
         # @return [Numeric] number of bytes written to disk.
-        def dump contents, filepath
-          raise NotImplementedError
+        # @raise [NotImplementedError] when not overridden by a subclass
+        def dump _contents, _filepath
+          not_implemented
         end
       end
     end

data/lib/rambling/trie/serializers/yaml.rb

@@ -17,6 +17,11 @@ module Rambling
         # @return [Nodes::Node] The deserialized {Nodes::Node Node}.
         # @see https://ruby-doc.org/3.3.0/exts/psych/Psych.html#method-c-safe_load Psych.safe_load
         def load filepath
+          warn <<~WARN.chomp.tr("\n", ' ')
+            WARNING: YAML aliases are enabled.
+            Loading untrusted YAML with aliases: true can trigger a billion-laughs memory attack.
+            Only load YAML data from trusted sources.
+          WARN
           require 'yaml'
           ::YAML.safe_load(
             serializer.load(filepath),

data/lib/rambling/trie/serializers/zip.rb

@@ -18,47 +18,47 @@ module Rambling
         # Unzip contents from specified filepath and load in contents from
         # unzipped files.
         # @param [String] filepath the filepath to load contents from.
-        # @return [TContents] all contents of the unzipped loaded file.
+        # @return [Nodes::Node] all contents of the unzipped loaded file.
         # @see https://github.com/rubyzip/rubyzip#reading-a-zip-file Zip
         #   reading a file
         def load filepath
           require 'zip'
 
-          ::Zip::File.open filepath do |zip|
-            entry = zip.entries.first
-            raise unless entry
+          clean_up_tmp_files do |tmp_paths|
+            ::Zip::File.open filepath do |zip|
+              entry = zip.entries.first
+              raise unless entry
 
-            entry_name = entry.name
-            entry_path = path entry_name
-            entry.extract ::File.basename(entry_path), destination_directory: tmp_path
+              entry_name = entry.name
+              entry_path = path_with_random_prefix entry_name
+              tmp_paths << entry_path
 
-            serializer = serializers.resolve entry_name
-            raise unless serializer
+              entry.extract ::File.basename(entry_path), destination_directory: tmp_path
 
-            serializer.load entry_path
+              (serializers.resolve(entry_name) || raise).load entry_path
+            end
           end
         end
 
         # Dumps contents and zips into a specified filepath.
         # @param [String] contents the contents to dump.
         # @param [String] filepath the filepath to dump the contents to.
-        # @return [TContents] number of bytes written to disk.
+        # @return [Integer] number of bytes written to disk.
         # @see https://github.com/rubyzip/rubyzip#basic-zip-archive-creation
         #   Zip archive creation
         def dump contents, filepath
           require 'zip'
 
-          ::Zip::File.open filepath, create: true do |zip|
-            filename = ::File.basename filepath, '.zip'
+          clean_up_tmp_files do |tmp_paths|
+            ::Zip::File.open filepath, create: true do |zip|
+              filename = ::File.basename filepath, '.zip'
 
-            entry_path = path filename
-            serializer = serializers.resolve filename
+              entry_path = path_with_random_prefix filename
+              tmp_paths << entry_path
 
-            raise unless serializer
-
-            serializer.dump contents, entry_path
-
-            zip.add filename, entry_path
+              (serializers.resolve(filename) || raise).dump contents, entry_path
+              zip.add filename, entry_path
+            end
           end
 
           ::File.size filepath
@@ -76,10 +76,20 @@ module Rambling
           properties.tmp_path
         end
 
-        def path filename
+        def path_with_random_prefix filename
           require 'securerandom'
           ::File.join tmp_path, "#{SecureRandom.uuid}-#{filename}"
         end
+
+        def clean_up_tmp_files
+          # @type var tmp_paths: Array[String]
+          tmp_paths = []
+          begin
+            yield tmp_paths
+          ensure
+            tmp_paths.each { |path| ::FileUtils.rm_f path }
+          end
+        end
       end
     end
   end

data/lib/rambling/trie/stringifyable.rb

@@ -6,12 +6,9 @@ module Rambling
     module Stringifyable
       # String representation of the current node, if it is a terminal node.
       # @return [String] the string representation of the current node.
-      # @raise [InvalidOperation] if node is not terminal or is root.
+      # @raise [InvalidOperation] if the node has a letter and is not terminal.
       def as_word
-        if letter && !terminal?
-          raise Rambling::Trie::InvalidOperation,
-            'Cannot represent branch as a word'
-        end
+        raise Rambling::Trie::InvalidOperation, 'Cannot represent branch as a word' if letter && !terminal?
 
         to_s
       end

data/lib/rambling/trie/version.rb

@@ -3,6 +3,6 @@
 module Rambling
   module Trie
     # Current version of the rambling-trie.
-    VERSION = '2.6.0'
+    VERSION = '2.7.0'
   end
 end

data/lib/rambling/trie.rb

@@ -2,7 +2,7 @@
 
 path = File.join 'rambling', 'trie'
 %w(
-  comparable compressible compressor configuration container enumerable inspectable invalid_operation
+  comparable compressible compressor configuration container enumerable inspectable invalid_operation not_implemented
   readers serializers stringifyable nodes version
 ).each { |file| require File.join(path, file) }
 
@@ -10,6 +10,9 @@ path = File.join 'rambling', 'trie'
 module Rambling
   # Entry point for `rambling-trie` API.
   module Trie
+    PROPERTIES_MUTEX = Mutex.new
+    private_constant :PROPERTIES_MUTEX
+
     class << self
       # Creates a new `Rambling::Trie`. Entry point for the `rambling-trie` API.
       # @param [String, nil] filepath the file to load the words from.
@@ -21,11 +24,9 @@ module Rambling
         root = root_builder.call
 
         Rambling::Trie::Container.new root, compressor do |container|
-          # noinspection RubyMismatchedArgumentType
           if filepath
-            reader ||= readers.resolve filepath
-            # noinspection RubyMismatchedArgumentType,RubyNilAnalysis
-            (reader || raise).each_word(filepath) { |word| container << word }
+            input_reader = reader || readers.resolve(filepath) || raise(ArgumentError, "no reader for #{filepath}")
+            input_reader.each_word(filepath) { |word| container << word }
           end
 
           yield container if block_given? # steep:ignore
@@ -62,7 +63,6 @@ module Rambling
       # @see Serializers Serializers.
       def dump trie, filepath, serializer = nil
         serializer ||= serializers.resolve filepath
-        # noinspection RubyNilAnalysis
         (serializer || raise).dump trie.root, filepath
       end
 
@@ -77,7 +77,11 @@ module Rambling
       private
 
       def properties
-        @properties ||= Rambling::Trie::Configuration::Properties.new
+        return @properties if @properties
+
+        PROPERTIES_MUTEX.synchronize do
+          @properties ||= Rambling::Trie::Configuration::Properties.new
+        end
       end
 
       def readers

data/sig/lib/rambling/trie/comparable.rbs

@@ -1,13 +1,15 @@
 module Rambling
   module Trie
-    module Comparable[TValue < _Inspect]
+    module Comparable[TValue < BasicObject & _Inspect & _Nilable]
       def ==: (Nodes::Node[TValue]) -> bool
 
       private
 
       # abstract methods
 
-      def letter: -> Symbol
+      def letter: -> Symbol?
+
+      def value: -> TValue?
 
       def terminal?: -> bool
 

data/sig/lib/rambling/trie/compressible.rbs

@@ -1,6 +1,6 @@
 module Rambling
   module Trie
-    module Compressible[TValue < _Inspect]
+    module Compressible[TValue < BasicObject & _Inspect & _Nilable]
       def compressible?: -> bool
 
       private

data/sig/lib/rambling/trie/compressor.rbs

@@ -1,6 +1,6 @@
 module Rambling
   module Trie
-    class Compressor[TValue < _Inspect]
+    class Compressor[TValue < BasicObject & _Inspect & _Nilable]
       def compress: (Nodes::Node[TValue]?) -> Nodes::Compressed[TValue]?
 
       private

data/sig/lib/rambling/trie/configuration/properties.rbs

@@ -1,7 +1,7 @@
 module Rambling
   module Trie
     module Configuration
-      class Properties[TValue < _Inspect]
+      class Properties[TValue < BasicObject & _Inspect & _Nilable]
         attr_reader readers: ProviderCollection[Readers::Reader]
         attr_reader serializers: ProviderCollection[Serializers::Serializer[Nodes::Node[TValue]]]
         attr_accessor compressor: Compressor[TValue]

data/sig/lib/rambling/trie/container.rbs

@@ -1,6 +1,6 @@
 module Rambling
   module Trie
-    class Container[TValue < _Inspect]
+    class Container[TValue < BasicObject & _Inspect & _Nilable]
       include ::Enumerable[String]
 
       @compressor: Compressor[TValue]
@@ -17,15 +17,16 @@ module Rambling
 
       def compress: -> Container[TValue]
 
-      def each: { (String) -> void } -> (Enumerator[String, void] | Enumerable[TValue])
+      def each: { (String) -> void } -> Container[TValue]
+                | -> Enumerator[String, void]
 
-      def partial_word?: (String) -> bool
+      def partial_word?: (?String) -> bool
 
       def push: (*String) -> Array[Nodes::Node[TValue]]
 
-      def word?: (String) -> bool
+      def word?: (?String) -> bool
 
-      def scan: (String) -> Array[String]
+      def scan: (?String) -> Array[String]
 
       def words_within: (String) -> Array[String]
 
@@ -45,11 +46,11 @@ module Rambling
 
       def key?: (Symbol) -> bool
 
-      def size: -> Numeric
+      def size: -> Integer
 
       alias include? word?
       alias match? partial_word?
-      alias words? scan
+      alias words scan
       alias << add
       alias has_key? key?
       alias has_letter? key?
@@ -59,7 +60,7 @@ module Rambling
       attr_reader compressor: Compressor[TValue]
       attr_writer root: Nodes::Node[TValue]
 
-      def words_within_root: (String) ?{ (String) -> void } -> Enumerator[String, void]
+      def words_within_root: (String) ?{ (String) -> void } -> (Container[TValue] | Enumerator[String, void])
 
       def compress_root: -> Nodes::Compressed[TValue]
 

data/sig/lib/rambling/trie/enumerable.rbs

@@ -1,13 +1,12 @@
 module Rambling
   module Trie
-    module Enumerable[TValue < _Inspect]
+    module Enumerable[TValue < BasicObject & _Inspect & _Nilable]
       include ::Enumerable[String]
 
-      EMPTY_ENUMERATOR: Enumerator[String, void]
-
       alias size count
 
-      def each: { (String) -> void } -> (Enumerator[String, void] | Enumerable[TValue])
+      def each: { (String) -> void } -> Enumerable[TValue]
+                | -> Enumerator[String, void]
 
       private
 
@@ -15,6 +14,8 @@ module Rambling
 
       def as_word: -> String
 
+      def empty_enum: -> Enumerator[String, void]
+
       def terminal?: -> bool
 
       def children_tree: -> Hash[Symbol, Nodes::Node[TValue]]

data/sig/lib/rambling/trie/inspectable.rbs

@@ -1,6 +1,6 @@
 module Rambling
   module Trie
-    module Inspectable[TValue < _Inspect]
+    module Inspectable[TValue < BasicObject & _Inspect & _Nilable]
 
       def inspect: -> String
 
@@ -20,9 +20,9 @@ module Rambling
 
       # abstract methods
 
-      def letter: -> Symbol
+      def letter: -> Symbol?
 
-      def value: -> TValue
+      def value: -> TValue?
 
       def terminal: -> bool?
 

data/sig/lib/rambling/trie/nodes/compressed.rbs

@@ -1,10 +1,10 @@
 module Rambling
   module Trie
     module Nodes
-      class Compressed[TValue < _Inspect] < Node[TValue]
+      class Compressed[TValue < BasicObject & _Inspect & _Nilable] < Node[TValue]
         def initialize: (?Symbol?, ?Node[TValue]?, ?Hash[Symbol, Node[TValue]]) -> void
 
-        def add: (Array[Symbol], ?TValue) -> Node[TValue]
+        def add: (Array[Symbol], ?TValue?) -> Node[TValue]
 
         def compressed?: -> bool
 
@@ -14,6 +14,8 @@ module Rambling
 
         def children_match_prefix: (Array[String]) { (String) -> void } -> Enumerator[String, void]
 
+        def match_child_prefix: (Node[TValue], Array[String]) { (String) -> void } -> Enumerator[String, void]
+
         def partial_word_chars?: (Array[String]) -> bool
 
         def word_chars?: (Array[String]) -> bool

data/sig/lib/rambling/trie/nodes/missing.rbs

@@ -1,8 +1,16 @@
 module Rambling
   module Trie
     module Nodes
-      class Missing[TValue < _Inspect] < Node[TValue]
+      class Missing[TValue < BasicObject & _Inspect & _Nilable] < Node[TValue]
         def initialize: -> void
+        def partial_word?: (Array[String] chars) -> bool
+
+        private
+
+        def word_chars?: (Array[String] chars) -> bool
+        def closest_node: (Array[String] chars) -> Node[TValue]
+        def children_match_prefix: (Array[String] chars) -> void
+                                 | (Array[String] chars) { (String word) -> void } -> void
       end
     end
   end

data/sig/lib/rambling/trie/nodes/node.rbs

@@ -1,7 +1,8 @@
 module Rambling
   module Trie
     module Nodes
-      class Node[TValue < _Inspect]
+      class Node[TValue < BasicObject & _Inspect & _Nilable]
+        include NotImplemented
         include Compressible[TValue]
         include Enumerable[TValue]
         include Comparable[TValue]
@@ -13,7 +14,7 @@ module Rambling
         attr_accessor parent: Node[TValue]?
         attr_accessor value: TValue?
 
-        def initialize: (?Symbol?, ?Node[TValue]?, ?Hash[Symbol, Node[TValue]]) -> void
+        def initialize: (?Symbol?, ?Node[TValue]?, ?Hash[Symbol, Node[TValue]]?) -> void
 
         def add: (Array[Symbol], ?TValue?) -> Node[TValue]
 

data/sig/lib/rambling/trie/nodes/raw.rbs

@@ -1,7 +1,7 @@
 module Rambling
   module Trie
     module Nodes
-      class Raw[TValue < _Inspect] < Node[TValue]
+      class Raw[TValue < BasicObject & _Inspect & _Nilable] < Node[TValue]
         def add: (Array[Symbol], ?TValue?) -> Node[TValue]
 
         def compressed?: -> bool

data/sig/lib/rambling/trie/not_implemented.rbs

@@ -0,0 +1,10 @@
+module Rambling
+  module Trie
+    # @api private
+    module NotImplemented : ::Object
+      private
+
+      def not_implemented: () -> bot
+    end
+  end
+end

data/sig/lib/rambling/trie/readers/plain_text.rbs

@@ -2,7 +2,7 @@ module Rambling
   module Trie
     module Readers
       class PlainText < Reader
-        def each_word: (String) { (String?) -> void } -> (Enumerator[String?, void] | PlainText)
+        def each_word: (String) { (String) -> void } -> (Enumerator[String, void] | PlainText)
       end
     end
   end

data/sig/lib/rambling/trie/readers/reader.rbs

@@ -2,6 +2,8 @@ module Rambling
   module Trie
     module Readers
       class Reader
+        include NotImplemented
+
         def each_word: (String) { (String) -> void } -> (Enumerator[String, void] | Reader)
       end
     end

data/sig/lib/rambling/trie/serializers/marshal.rbs

@@ -1,7 +1,7 @@
 module Rambling
   module Trie
     module Serializers
-      class Marshal[TValue < _Inspect] < Serializer[Nodes::Node[TValue]]
+      class Marshal[TValue < BasicObject & _Inspect & _Nilable] < Serializer[Nodes::Node[TValue]]
         @serializer: Serializer[String]
 
         private

data/sig/lib/rambling/trie/serializers/serializer.rbs

@@ -2,6 +2,8 @@ module Rambling
   module Trie
     module Serializers
       class Serializer[TContents]
+        include NotImplemented
+
         def load: (String) -> TContents
         def dump: (TContents, String) -> Numeric
       end

data/sig/lib/rambling/trie/serializers/yaml.rbs

@@ -1,7 +1,7 @@
 module Rambling
   module Trie
     module Serializers
-      class Yaml[TValue < _Inspect] < Serializer[Nodes::Node[TValue]]
+      class Yaml[TValue < BasicObject & _Inspect & _Nilable] < Serializer[Nodes::Node[TValue]]
         @serializer: Serializer[String]
 
         private

data/sig/lib/rambling/trie/serializers/zip.rbs

@@ -1,7 +1,7 @@
 module Rambling
   module Trie
     module Serializers
-      class Zip[TValue < _Inspect] < Serializer[Nodes::Node[TValue]]
+      class Zip[TValue < BasicObject & _Inspect & _Nilable] < Serializer[Nodes::Node[TValue]]
         @properties: Configuration::Properties[TValue]
 
         def initialize: (Configuration::Properties[TValue]) -> void
@@ -14,7 +14,9 @@ module Rambling
 
         def tmp_path: -> String
 
-        def path: (String) -> String
+        def path_with_random_prefix: (String) -> String
+
+        def clean_up_tmp_files: [T] { (Array[String]) -> T } -> T
       end
     end
   end

data/sig/lib/rambling/trie/stringifyable.rbs

@@ -1,6 +1,6 @@
 module Rambling
   module Trie
-    module Stringifyable[TValue < _Inspect]
+    module Stringifyable[TValue < BasicObject & _Inspect & _Nilable]
       def as_word: -> String
 
       def to_s: -> String
@@ -9,7 +9,7 @@ module Rambling
 
       # abstract methods
 
-      def letter: -> Symbol
+      def letter: -> Symbol?
 
       def terminal?: -> bool
 

data/sig/lib/rambling/trie.rbs

@@ -2,24 +2,26 @@ module Rambling
   module Trie
     VERSION: String
 
-    def self.create: [TValue < _Inspect] (?String?, ?Readers::Reader?) ?{ (Container[TValue]) -> void } -> Container[TValue]
+    def self.create: [TValue < BasicObject & _Inspect & _Nilable] (?String?, ?Readers::Reader?) ?{ (Container[TValue]) -> void } -> Container[TValue]
 
-    def self.load: [TValue < _Inspect] (String, ?Serializers::Serializer[Nodes::Node[TValue]]?) ?{ (Container[TValue]) -> void } -> Container[TValue]
+    def self.load: [TValue < BasicObject & _Inspect & _Nilable] (String, ?Serializers::Serializer[Nodes::Node[TValue]]?) ?{ (Container[TValue]) -> void } -> Container[TValue]
 
-    def self.dump: [TValue < _Inspect] (Container[TValue], String, ?Serializers::Serializer[Nodes::Node[TValue]]?) -> void
+    def self.dump: [TValue < BasicObject & _Inspect & _Nilable] (Container[TValue], String, ?Serializers::Serializer[Nodes::Node[TValue]]?) -> void
 
-    def self.config: [TValue < _Inspect] ?{ (Configuration::Properties[TValue]) -> void } -> Configuration::Properties[TValue]
+    def self.config: [TValue < BasicObject & _Inspect & _Nilable] ?{ (Configuration::Properties[TValue]) -> void } -> Configuration::Properties[TValue]
 
     private
 
-    def self.properties: [TValue < _Inspect] -> Configuration::Properties[TValue]
+    PROPERTIES_MUTEX: Mutex
+
+    def self.properties: [TValue < BasicObject & _Inspect & _Nilable] -> Configuration::Properties[TValue]
 
     def self.readers: -> Configuration::ProviderCollection[Readers::Reader]
 
-    def self.serializers: [TValue < _Inspect] -> Configuration::ProviderCollection[Serializers::Serializer[Nodes::Node[TValue]]]
+    def self.serializers: [TValue < BasicObject & _Inspect & _Nilable] -> Configuration::ProviderCollection[Serializers::Serializer[Nodes::Node[TValue]]]
 
-    def self.compressor: [TValue < _Inspect] -> Compressor[TValue]
+    def self.compressor: [TValue < BasicObject & _Inspect & _Nilable] -> Compressor[TValue]
 
-    def self.root_builder: [TValue < _Inspect] -> ^() -> Nodes::Node[TValue]
+    def self.root_builder: [TValue < BasicObject & _Inspect & _Nilable] -> ^() -> Nodes::Node[TValue]
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rambling-trie
 version: !ruby/object:Gem::Version
-  version: 2.6.0
+  version: 2.7.0
 platform: ruby
 authors:
 - Edgar Gonzalez
@@ -43,6 +43,7 @@ files:
 - lib/rambling/trie/nodes/missing.rb
 - lib/rambling/trie/nodes/node.rb
 - lib/rambling/trie/nodes/raw.rb
+- lib/rambling/trie/not_implemented.rb
 - lib/rambling/trie/readers.rb
 - lib/rambling/trie/readers/plain_text.rb
 - lib/rambling/trie/readers/reader.rb
@@ -70,6 +71,7 @@ files:
 - sig/lib/rambling/trie/nodes/missing.rbs
 - sig/lib/rambling/trie/nodes/node.rbs
 - sig/lib/rambling/trie/nodes/raw.rbs
+- sig/lib/rambling/trie/not_implemented.rbs
 - sig/lib/rambling/trie/readers/plain_text.rbs
 - sig/lib/rambling/trie/readers/reader.rbs
 - sig/lib/rambling/trie/serializers/file.rbs
@@ -78,8 +80,6 @@ files:
 - sig/lib/rambling/trie/serializers/yaml.rbs
 - sig/lib/rambling/trie/serializers/zip.rbs
 - sig/lib/rambling/trie/stringifyable.rbs
-- sig/lib/zip/entry.rbs
-- sig/lib/zip/file.rbs
 homepage: https://github.com/gonzedge/rambling-trie
 licenses:
 - MIT
@@ -104,7 +104,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.6
 specification_version: 4
 summary: A Ruby implementation of the trie data structure.
 test_files: []

data/sig/lib/zip/entry.rbs

@@ -1,11 +0,0 @@
-module Zip
-  class Entry
-    include Enumerable[Entry]
-
-    def name: -> String
-
-    def extract: (String, ?destination_directory: String?) -> void
-
-    def each: ?{ (Entry) -> void } -> (Enumerator[Entry, void])
-  end
-end

data/sig/lib/zip/file.rbs

@@ -1,9 +0,0 @@
-module Zip
-  class File
-    def self.open: [TContent] (String, ?create: bool?) { (File) -> TContent } -> TContent
-
-    def entries: -> Array[Entry]
-
-    def add: (String, String) -> void
-  end
-end