rambling-trie 2.5.1 → 2.7.0

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
@@ -31,14 +32,20 @@ module Rambling
         # @return [Node, nil] the parent of the current node.
         attr_accessor :parent
 
+        # Arbitrary value stored in this 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.
@@ -50,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.
@@ -133,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#[]
@@ -170,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,13 +9,16 @@ 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.
-        def add reversed_chars
+        # @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?
-            terminal! unless root?
+            unless root?
+              self.value = value
+              terminal!
+            end
             self
           else
-            add_to_children_tree reversed_chars
+            add_to_children_tree reversed_chars, value
           end
         end
 
@@ -27,10 +30,10 @@ module Rambling
 
         private
 
-        def add_to_children_tree chars
+        def add_to_children_tree chars, value = nil
           letter = chars.pop || raise
           child = children_tree[letter] || new_node(letter)
-          child.add chars
+          child.add chars, value
           child
         end
 
@@ -67,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 entry_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, ::Zip::File::CREATE 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.5.1'
+    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,14 +24,12 @@ 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?
+          yield container if block_given? # steep:ignore
         end
       end
 
@@ -37,7 +38,7 @@ module Rambling
       # Available formats are `yml`, `marshal`, and `zip` versions of all the
       # previous formats. You can also define your own.
       # @param [String] filepath the file to load the words from.
-      # @param [Serializer, nil] serializer the object responsible of loading the trie from disk.
+      # @param [Serializer, nil] serializer the object responsible for loading the trie from disk.
       # @return [Container] the trie just loaded.
       # @yield [Container] the trie just loaded.
       # @see Rambling::Trie::Serializers Serializers.
@@ -47,7 +48,7 @@ module Rambling
         serializer ||= serializers.resolve filepath
         root = (serializer || raise).load filepath
         Rambling::Trie::Container.new root, compressor do |container|
-          yield container if block_given?
+          yield container if block_given? # steep:ignore
         end
       end
 
@@ -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/rambling-trie.gemspec

@@ -31,5 +31,5 @@ Gem::Specification.new do |gem|
   gem.license = 'MIT'
   gem.version = Rambling::Trie::VERSION
   gem.platform = Gem::Platform::RUBY
-  gem.required_ruby_version = '>= 3.1', '< 4'
+  gem.required_ruby_version = '>= 3.2', '< 5'
 end

data/sig/lib/nilable.rbs

@@ -0,0 +1,3 @@
+interface _Nilable
+  def nil?: -> bool
+end

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

@@ -1,17 +1,19 @@
 module Rambling
   module Trie
-    module Comparable
-      def ==: (Nodes::Node) -> bool
+    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
 
-      def children_tree: -> Hash[Symbol, Nodes::Node]
+      def children_tree: -> Hash[Symbol, Nodes::Node[TValue]]
     end
   end
 end

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

@@ -1,6 +1,6 @@
 module Rambling
   module Trie
-    module Compressible
+    module Compressible[TValue < BasicObject & _Inspect & _Nilable]
       def compressible?: -> bool
 
       private
@@ -11,7 +11,7 @@ module Rambling
 
       def terminal?: -> bool
 
-      def children_tree: -> Hash[Symbol, Nodes::Node]
+      def children_tree: -> Hash[Symbol, Nodes::Node[TValue]]
     end
   end
 end

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

@@ -1,17 +1,17 @@
 module Rambling
   module Trie
-    class Compressor
-      def compress: (Nodes::Node?) -> Nodes::Compressed?
+    class Compressor[TValue < BasicObject & _Inspect & _Nilable]
+      def compress: (Nodes::Node[TValue]?) -> Nodes::Compressed[TValue]?
 
       private
 
-      def compress_only_child_and_merge: (Nodes::Node) -> Nodes::Compressed
+      def compress_only_child_and_merge: (Nodes::Node[TValue]) -> Nodes::Compressed[TValue]
 
-      def merge: (Nodes::Node, Nodes::Node) -> Nodes::Compressed
+      def merge: (Nodes::Node[TValue], Nodes::Node[TValue]) -> Nodes::Compressed[TValue]
 
-      def compress_children_and_copy: (Nodes::Node) -> Nodes::Compressed
+      def compress_children_and_copy: (Nodes::Node[TValue]) -> Nodes::Compressed[TValue]
 
-      def compress_children: (Hash[Symbol, Nodes::Node]) -> Hash[Symbol, Nodes::Node]
+      def compress_children: (Hash[Symbol, Nodes::Node[TValue]]) -> Hash[Symbol, Nodes::Node[TValue]]
     end
   end
 end

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

@@ -1,11 +1,11 @@
 module Rambling
   module Trie
     module Configuration
-      class Properties
+      class Properties[TValue < BasicObject & _Inspect & _Nilable]
         attr_reader readers: ProviderCollection[Readers::Reader]
-        attr_reader serializers: ProviderCollection[Serializers::Serializer[Nodes::Node]]
-        attr_accessor compressor: Compressor
-        attr_accessor root_builder: ^() -> Nodes::Node
+        attr_reader serializers: ProviderCollection[Serializers::Serializer[Nodes::Node[TValue]]]
+        attr_accessor compressor: Compressor[TValue]
+        attr_accessor root_builder: ^() -> Nodes::Node[TValue]
         attr_accessor tmp_path: String
 
         def initialize: -> void
@@ -15,7 +15,7 @@ module Rambling
         private
 
         attr_writer readers: ProviderCollection[Readers::Reader]
-        attr_writer serializers: ProviderCollection[Serializers::Serializer[Nodes::Node]]
+        attr_writer serializers: ProviderCollection[Serializers::Serializer[Nodes::Node[TValue]]]
 
         def reset_readers: -> void
 

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

@@ -2,10 +2,6 @@ module Rambling
   module Trie
     module Configuration
       class ProviderCollection[TProvider < _Nilable]
-        interface _Nilable
-          def nil?: -> bool
-        end
-
         @providers: Hash[Symbol, TProvider]
 
         attr_reader name: Symbol

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

@@ -1,43 +1,44 @@
 module Rambling
   module Trie
-    class Container
+    class Container[TValue < BasicObject & _Inspect & _Nilable]
       include ::Enumerable[String]
 
-      @compressor: Compressor
+      @compressor: Compressor[TValue]
 
-      attr_reader root: Nodes::Node
+      attr_reader root: Nodes::Node[TValue]
 
-      def initialize: (Nodes::Node, Compressor) ?{ (Container) -> void } -> void
+      def initialize: (Nodes::Node[TValue], Compressor[TValue]) ?{ (Container[TValue]) -> void } -> void
 
-      def add: (String) -> Nodes::Node
+      def add: (String, ?TValue?) -> Nodes::Node[TValue]
 
-      def concat: (Array[String]) -> Array[Nodes::Node]
+      def concat: (Array[String], ?Array[TValue?]?) -> Array[Nodes::Node[TValue]]
 
-      def compress!: -> Container
+      def compress!: -> Container[TValue]
 
-      def compress: -> Container
+      def compress: -> Container[TValue]
 
-      def each: { (String) -> void } -> (Enumerator[String, void] | Enumerable)
+      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]
+      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]
 
       def words_within?: (String) -> bool
 
-      def ==: (Container) -> bool
+      def ==: (Container[TValue]) -> bool
 
-      def []: (Symbol) -> Nodes::Node
+      def []: (Symbol) -> Nodes::Node[TValue]?
 
-      def children: -> Array[Nodes::Node]
+      def children: -> Array[Nodes::Node[TValue]]
 
-      def children_tree: -> Hash[Symbol, Nodes::Node]
+      def children_tree: -> Hash[Symbol, Nodes::Node[TValue]]
 
       def compressed?: -> bool
 
@@ -45,23 +46,23 @@ 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?
 
       private
 
-      attr_reader compressor: Compressor
-      attr_writer root: Nodes::Node
+      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
+      def compress_root: -> Nodes::Compressed[TValue]
 
       def reversed_char_symbols: (String) -> Array[Symbol]
     end