utils 0.68.0 → 0.69.0

data/lib/utils/line_blamer.rb

@@ -1,13 +1,41 @@
 module Utils
   class LineBlamer
+    # Initializes a new LineBlamer instance to analyze source code line
+    # information.
+    #
+    # @param file [ String ] the path to the file containing the line of code
+    # @param lineno [ Integer ] the line number within the file (defaults to 1)
     def initialize(file, lineno = 1)
       @file, @lineno = file, lineno
     end
 
+    # Finds the source location of a line and creates a new LineBlamer instance.
+    #
+    # This method extracts the file path and line number from the given line
+    # object using its source_location method. If a valid location is found, it
+    # initializes and returns a new LineBlamer instance with the extracted file
+    # path and line number.
+    #
+    # @param line [ Object ] the line object to analyze for source location
+    # information
+    #
+    # @return [ Utils::LineBlamer, nil ] a new LineBlamer instance if the line
+    # has a valid source location, otherwise nil
     def self.for_line(line)
       location = line.source_location and new(*location)
     end
 
+    # Performs git blame on a specific line of code and returns the result.
+    #
+    # This method executes a git blame command to analyze the specified file
+    # and line number, retrieving information about when and by whom the line
+    # was last modified. It handles potential errors from git by suppressing
+    # stderr output and returns nil if git is not available or the operation
+    # fails.
+    #
+    # @param options [ String ] additional options to pass to the git blame command
+    #
+    # @return [ String, nil ] the output of the git blame command if successful, otherwise nil
     def perform(options = '')
       `git 2>/dev/null blame #{options} -L #@lineno,+1 "#@file"`.full?
     end

data/lib/utils/line_formatter.rb

@@ -12,6 +12,11 @@ else
       ::RSpec::Core::Formatters.register self, :start, :close,
         :example_passed, :example_pending, :example_failed, :dump_summary
 
+      # The initialize method sets up the error logging system by creating a
+      # file handle for writing error messages and ensuring the output is
+      # synchronized.
+      #
+      # @param output [ IO ] the output stream to be used for logging errors
       def initialize(output)
         @output = output
         @output.sync = true
@@ -20,31 +25,82 @@ else
         @errors_lst.sync = true
       end
 
+      # The output reader method provides access to the output storage.
+      #
+      # @return [ Array ] the array containing the collected output items
       attr_reader :output
 
+      # The start method initializes the error logging output.
+      #
+      # This method writes a header message to the output indicating where the
+      # error list will be stored, followed by a separator line made of dashes
+      # that spans the width of the terminal.
+      #
+      # @param _ignore [ Object ] this parameter is ignored and exists for
+      # interface compatibility
       def start(_ignore)
         output.puts "Storing error list in #{@errors_lst.path.inspect}: "
         output.puts ?- * Tins::Terminal.columns
       end
 
+      # The close method closes the error log file handle.
+      #
+      # This method is responsible for properly closing the file handle
+      # associated with the error log file, ensuring that all buffered data is
+      # written and system resources are released.
+      #
+      # @param _ignore [ Object ] ignored parameter, present for interface
+      # compatibility
       def close(_ignore)
         @errors_lst.close
       end
 
+      # The dump_summary method outputs a formatted summary line to both the
+      # errors log and the standard output.
+      #
+      # This method generates a summary line using the summary_line method,
+      # then writes it to both the error log file and the standard output, with
+      # decorative lines of equals signs for visual separation in each output
+      # stream.
+      #
+      # @param summary [ Object ] the summary object to be processed and displayed
       def dump_summary(summary)
         line = summary_line(summary)
         @errors_lst.puts ?= * 80, line
         output.puts ?= * Tins::Terminal.columns, line
       end
 
+      # The example_passed method outputs a formatted line for a passed test
+      # example.
+      #
+      # This method takes a test example and formats it using the internal format_line method,
+      # then writes the formatted output to the designated output stream.
+      #
+      # @param example [ Object ] the test example that has passed
       def example_passed(example)
         output.puts format_line(example)
       end
 
+      # The example_pending method outputs a formatted line for a pending test
+      # example.
+      #
+      # This method takes a test example that is pending and formats it using
+      # the internal format_line method before outputting it to the console.
+      #
+      # @param example [ Object ] the test example that is pending
       def example_pending(example)
         output.puts format_line(example)
       end
 
+      # The example_failed method handles the processing of failed test
+      # examples.
+      #
+      # This method manages the logging and output of failed test results by
+      # first writing the failure details to an error file, then formatting and
+      # displaying the failure information to the output stream, and finally
+      # dumping the full failure details.
+      #
+      # @param example [ Object ] the test example that failed
       def example_failed(example)
         dump_failure_to_error_file(example)
         output.puts format_line(example)
@@ -53,6 +109,18 @@ else
 
       private
 
+      # The summary_line method formats a summary string containing test
+      # execution statistics.
+      #
+      # This method takes a summary object and generates a formatted string
+      # that includes the number of failed tests, total tests, failure
+      # percentage, pending tests, pending percentage, and the total execution
+      # duration.
+      #
+      # @param summary [ Object ] an object containing test execution statistics
+      #
+      # @return [ String ] a formatted summary string with test statistics and
+      # timing information
       def summary_line(summary)
         failure_percentage = 100 * summary.failure_count.to_f / summary.example_count
         failure_percentage.nan? and failure_percentage = 0.0
@@ -68,6 +136,13 @@ else
         ]
       end
 
+      # The dump_failure method outputs detailed information about a test
+      # failure.
+      #
+      # This method displays the description of the failing example along with
+      # the specific failure details for debugging purposes.
+      #
+      # @param example [ Object ] the test example that failed
       def dump_failure(example)
         output.puts(
           description(example, full: true),
@@ -75,10 +150,32 @@ else
         )
       end
 
+      # The read_failed_line method returns an empty string after stripping
+      # whitespace.
+      #
+      # This method is intended to provide a placeholder implementation for
+      # retrieving the failed line information from a test example, currently
+      # returning an empty stripped string regardless of the input.
+      #
+      # @param example [ Object ] the test example object
+      #
+      # @return [ String ] an empty string with whitespace stripped
       def read_failed_line(example)
         ''.strip
       end
 
+      # The dump_failure_for_example method constructs a formatted failure
+      # message for a test example.
+      #
+      # This method generates a detailed error report that includes the failing
+      # line of code, the exception class name, and the exception message. It
+      # processes the execution result
+      # of a test example to extract relevant information about why the test failed.
+      #
+      # @param example [ Object ] the test example object containing execution results
+      #
+      # @return [ String ] a formatted string containing the failure details including
+      #         the failing line, exception class, and exception message
       def dump_failure_for_example(example)
         result = ''
         exception = execution_result(example).exception
@@ -91,6 +188,19 @@ else
         result
       end
 
+      # The format_backtrace method processes and formats the backtrace
+      # information for an example.
+      #
+      # This method extracts the backtrace from the exception associated with
+      # an example, applies optional filtering based on a limit, and formats
+      # each line using relative paths. It can optionally wrap the formatted
+      # backtrace with folding markers when requested.
+      #
+      # @param example [ Object ] the example object containing the exception with backtrace
+      # @param folding [ TrueClass, FalseClass ] whether to wrap the backtrace with folding markers
+      # @param limit [ Integer, nil ] the maximum number of backtrace lines to include
+      #
+      # @return [ String ] the formatted backtrace as a string with lines separated by newlines
       def format_backtrace(example, folding: false, limit: nil)
         backtrace = execution_result(example).exception.backtrace
         backtrace.nil? and return ''
@@ -106,6 +216,15 @@ else
         result * ?\n
       end
 
+      # The dump_failure_to_error_file method writes failure information to an
+      # error log file.
+      #
+      # This method records detailed information about a failed test example,
+      # including the location, runtime, description, failure details, and
+      # backtrace. It uses file locking to ensure thread-safe writing to the
+      # error log file.
+      #
+      # @param example [ Object ] the test example that failed
       def dump_failure_to_error_file(example)
         @errors_lst.flock File::LOCK_EX
         @errors_lst.puts "%s\n%3.3fs %s\n%s\n%s" % [
@@ -116,10 +235,29 @@ else
         @errors_lst.flock File::LOCK_UN
       end
 
+      # The execution_result method retrieves the execution result metadata
+      # from an example.
+      #
+      # This method accesses the metadata hash associated with the example's
+      # underlying test case to extract the execution result information that
+      # was stored during test execution.
+      #
+      # @param example [ Object ] the example object containing test metadata
+      #
+      # @return [ Object ] the execution result metadata stored in the example's metadata hash
       def execution_result(example)
         example.example.metadata[:execution_result]
       end
 
+      # The description method retrieves either the full or abbreviated
+      # description of an example.
+      #
+      # @param example [ Object ] the example object containing description
+      # information
+      # @param full [ TrueClass, FalseClass ] determines whether to return the
+      # full description or abbreviated version
+      #
+      # @return [ String ] the appropriate description based on the full parameter value
       def description(example, full: ENV['VERBOSE'].to_i == 1)
         if full
           example.example.full_description
@@ -128,10 +266,29 @@ else
         end
       end
 
+      # The run_time method retrieves the execution time of a test example.
+      #
+      # This method accesses the execution result of a given test example and
+      # returns the run time associated with that execution.
+      #
+      # @param example [ Object ] the test example object to get run time for
+      #
+      # @return [ Float, nil ] the execution time of the example or nil if not available
       def run_time(example)
         execution_result(example).run_time
       end
 
+      # The format_line method formats and colors test execution results for
+      # display.
+      #
+      # This method takes a test example and creates a formatted string that
+      # includes the location, run time, and description of the test. It
+      # applies color coding based on the test result status and ensures the
+      # output fits within the terminal width.
+      #
+      # @param example [ Object ] the test example to format
+      #
+      # @return [ String ] the formatted and colorized test result string
       def format_line(example)
         args = [ location(example), run_time(example), description(example) ]
         uncolored = "%s # S %3.3fs %s" % args
@@ -148,18 +305,59 @@ else
         end
       end
 
+      # The success_color method applies green color formatting to the provided
+      # text.
+      #
+      # This method wraps the input text with ANSI color codes to display it in
+      # green, which is typically used to indicate successful or positive
+      # outcomes in terminal output.
+      #
+      # @param text [ String ] the text to be formatted with green color
+      #
+      # @return [ String ] the input text wrapped with green color ANSI escape codes
       def success_color(text)
         Term::ANSIColor.green(text)
       end
 
+      # The failure_color method applies red color formatting to the provided
+      # text.
+      #
+      # This method wraps the input text with red color codes using the
+      # Term::ANSIColor library, making the text appear in red when displayed
+      # in compatible terminals.
+      #
+      # @param text [ String ] the text to be colorized in red
+      #
+      # @return [ String ] the colorized text wrapped with red formatting codes
       def failure_color(text)
         Term::ANSIColor.red(text)
       end
 
+      # The pending_color method applies yellow color formatting to the
+      # provided text.
+      #
+      # This method wraps the input text with yellow color codes using the
+      # Term::ANSIColor library, making the text appear in yellow when
+      # displayed in compatible terminals.
+      #
+      # @param text [ String ] the text to be colorized
+      #
+      # @return [ String ] the colorized text with yellow formatting applied
       def pending_color(text)
         Term::ANSIColor.yellow(text)
       end
 
+      # The location method extracts and formats the file path and line number
+      # for an RSpec example.
+      #
+      # This method retrieves the location information from the example's
+      # metadata, handling cases where the location might be nested within the
+      # example group. It then processes the location to return a relative path
+      # using RSpec's metadata helper.
+      #
+      # @param example [ Object ] the RSpec example object containing metadata
+      #
+      # @return [ String ] the relative file path and line number for the example
       def location(example)
         location = example.example.metadata[:location]
         unless location.include?(?/)

data/lib/utils/md5.rb

@@ -3,12 +3,26 @@ require 'digest/md5'
 module Utils
   module MD5
     class << self
+      # The buffer_size accessor method provides read and write access to the
+      # buffer_size instance variable.
+      #
+      # @return [ Integer ] the current buffer size value
       attr_accessor :buffer_size
     end
     self.buffer_size = 2 ** 20 - 1
 
     module_function
 
+    # Computes the MD5 hash digest for a given file.
+    #
+    # This method reads the entire contents of the specified file in binary
+    # mode and calculates its MD5 hash value. It uses a configurable buffer
+    # size for reading the file in chunks to optimize memory usage during the
+    # hashing process.
+    #
+    # @param filename [ String ] the path to the file for which to compute the MD5 hash
+    #
+    # @return [ String ] the hexadecimal representation of the MD5 hash digest
     def md5(filename)
       digest = Digest::MD5.new
       digest.reset

data/lib/utils/patterns.rb

@@ -1,6 +1,19 @@
 module Utils
   module Patterns
     class Pattern
+      # Initializes a new Pattern instance with the specified options.
+      #
+      # This method sets up the pattern configuration by storing the character
+      # set, case sensitivity flag, and pattern string. It validates that a
+      # pattern is provided and optionally filters the pattern characters based
+      # on the specified character set.
+      #
+      # @param opts [ Hash ] a hash containing the pattern configuration options
+      # @option opts [ String ] :cset the character set to filter pattern characters against
+      # @option opts [ TrueClass, FalseClass ] :icase whether the pattern matching should be case sensitive
+      # @option opts [ String ] :pattern the pattern string to be used for matching
+      #
+      # @raise [ ArgumentError ] if the pattern option is not provided
       def initialize(opts = {})
         @cset    = opts[:cset]
         @icase   = opts[:icase]
@@ -9,8 +22,23 @@ module Utils
         @pattern = @pattern.gsub(/[^#{@cset}]/, '') if @cset
       end
 
+      # Returns the matcher object used for pattern matching.
+      #
+      # @return [ Object ] the matcher object that handles pattern matching operations
       attr_reader :matcher
 
+      # The method_missing method delegates calls to the matcher object while
+      # handling UTF-8 encoding errors.
+      #
+      # This method acts as a fallback handler for undefined method calls,
+      # forwarding them to the internal matcher object. It specifically catches
+      # ArgumentError exceptions related to invalid byte sequences in UTF-8 and
+      # re-raises them unless they match the expected error pattern.
+      #
+      # @param a [ Array ] the arguments passed to the missing method
+      # @param b [ Proc ] the block passed to the missing method
+      #
+      # @return [ Object ] the result of the delegated method call on the matcher
       def method_missing(*a, &b)
         @matcher.__send__(*a, &b)
       rescue ArgumentError => e
@@ -19,24 +47,70 @@ module Utils
     end
 
     class FuzzyPattern < Pattern
+      # Initializes a fuzzy pattern matcher by processing the pattern string
+      # and compiling it into a regular expression.
+      #
+      # This method takes the configured pattern string and converts it into a
+      # regular expression that can match strings in a fuzzy manner, allowing
+      # for partial matches while preserving the order of characters. It
+      # handles case sensitivity based on the configuration.
+      #
+      # @param opts [ Hash ] a hash containing the pattern configuration options
+      # @option opts [ String ] :cset the character set to filter pattern characters against
+      # @option opts [ TrueClass, FalseClass ] :icase whether the pattern matching should be case sensitive
+      # @option opts [ String ] :pattern the pattern string to be used for matching
       def initialize(opts = {})
         super
         r = @pattern.split(//).grep(/[[:print:]]/).map { |x|
           "(#{Regexp.quote(x)})"
         } * '.*?'
         @matcher = Regexp.new(
-          "\\A(?:.*/.*?#{r}|.*#{r})",
-          @icase ? Regexp::IGNORECASE : 0)
+          "\\A(?:.*/.*?#{r}|.*#{r})", @icase ? Regexp::IGNORECASE : 0
+        )
       end
     end
 
     class RegexpPattern < Pattern
+      # Initializes a regular expression pattern matcher with the specified
+      # options.
+      #
+      # This method sets up a regular expression object based on the pattern
+      # string and case sensitivity configuration that was previously
+      # initialized in the parent class. It compiles the pattern into a Regexp
+      # object that can be used for matching operations throughout the pattern
+      # matching process.
+      #
+      # @param opts [ Hash ] a hash containing the pattern configuration options
+      # @option opts [ String ] :cset the character set to filter pattern characters against
+      # @option opts [ TrueClass, FalseClass ] :icase whether the pattern matching should be case sensitive
+      # @option opts [ String ] :pattern the pattern string to be used for matching
+      #
+      # @return [ Regexp ] a compiled regular expression object ready for pattern matching operations
       def initialize(opts = {})
         super
-        @matcher = Regexp.new(@pattern, @icase ? Regexp::IGNORECASE : 0)
+        @matcher = Regexp.new(
+          @pattern, @icase ? Regexp::IGNORECASE : 0
+        )
       end
     end
 
+    # Chooses and initializes a pattern matcher based on the provided argument
+    # and options.
+    #
+    # This method selects between a regular expression pattern matcher and a
+    # fuzzy pattern matcher depending on the value of the argument parameter
+    # and the default configuration.
+    # It validates that the argument is either 'r' (regexp) or 'f' (fuzzy) and
+    # raises an error if an invalid value is provided.
+    #
+    # @param argument [ String ] the argument string that determines the pattern type
+    # @param pattern_opts [ Hash ] the options to be passed to the pattern matcher constructor
+    # @param default [ String ] the default pattern type to use when argument is nil or empty
+    #
+    # @return [ Utils::Patterns::Pattern ] a new instance of either RegexpPattern or FuzzyPattern
+    #
+    # @raise [ ArgumentError ] if the argument does not match 'r' or 'f' patterns and is not nil
+    # @raise [ ArgumentError ] if the pattern option is not provided to the pattern matcher constructor
     def choose(argument, pattern_opts, default: ?f)
       case argument
       when /^r/, (default == ?r ? nil : :not)