utils 0.73.1 → 0.74.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eeb8c50e8895ed05192b62c4c7c86d0f5eccd34234e6878233c5324542c2c5ef
-  data.tar.gz: f0c4adb49862333e4c85fba3ccde54c1a899dffb23a0cd846123d4bcc6ee7fa8
+  metadata.gz: 86f1322a16463dd1af9021e0d2a9dc63dfc3704bdf3a8c71874c8f526b8aac0c
+  data.tar.gz: 8b645c35b3b852f14ad94aee06820b2c15da09306315e4061251e00f318d476c
 SHA512:
-  metadata.gz: 18e205eb300082bdd1341083a63ac508c80e3af31faabcbe4675ec4c2c7c3c7b5975e1479ec426aba98ebadad3dc2d8e66b0b351aeae092eb525a1caf23ff1a7
-  data.tar.gz: 8c3f8ec933935f36b4d79e5224dd49e71f5839bc152969f528b459f19240e743089ff7234e17eb644d6e19dda511eb8fdcf1a58e05cb4278752f831a9d87e5dd
+  metadata.gz: bd65623f8475906b5519177ee5ab518fc51111b0565c7fb8c3a904d92e0ffd1a4ed1e2fb3927fb82bfdd3cb94039645a5d40f383aabdb79805270cef364d7897
+  data.tar.gz: 7c1d0fc7b244523bf63900b5a2d5c3b2e427a7d224e3bdd10697f772d728a333f5d5a17c4a86bf5a2806e57af0b25a71b732d084dada16e8fa6c96f8b3670dec

data/Rakefile

@@ -14,7 +14,7 @@ GemHadar do
     map(&File.method(:basename))
   test_dir    'tests'
   ignore      '.*.sw[pon]', 'pkg', 'Gemfile.lock', '.rvmrc', '.AppleDouble',
-    'tags', '.bundle', '.DS_Store', '.byebug_history'
+    'tags', '.bundle', '.DS_Store', '.byebug_history', '.yardoc', 'doc'
   package_ignore '.gitignore', 'VERSION'
   readme      'README.md'
   licenses << 'GPL-2.0'

data/bin/code_comment

@@ -11,7 +11,7 @@
 # descriptions, parameters, return values, and exceptions.
 #
 # Requires:
-#   - Git repository with Ruby files in lib/, spec/, or test/ directories
+#   - Git repository with Ruby files in lib/, spec/, or tests/ directories
 #   - Ollama server running locally or accessible via OLLAMA_URL / OLLAMA_HOST
 #   - Configuration files in ~/.config/code_comment/
 #     - system.txt: System prompt for LLM
@@ -111,14 +111,18 @@ def build_method_prompt(construct_type, construct, context)
 
     Format requirements:
 
-    1. Focus on providing a description of the %{construct_type}'s purpose
+    1. focus on providing a description of the %{construct_type}'s purpose
        without including any code snippets.
-    2. You should omit the @raise if you are not sure.
-    3. Never use `, `ruby, ```, ```ruby in your response.
-    4. Never add any other remarks or explanation to your response.
-    5. Start each line of your comment with a single # character.
+    2. **always** output just the line comments starting each with a single #
+       character.
+    3. **never** output any executable ruby code like class or module
+       definitions, or method definitions or other code outside of such
+       comments.
+    4. you should omit the @raise if you are not sure.
+    5. never use `, `ruby, ```, ```ruby in your response.
+    6. never add any other remarks or explanation to your response.
   EOT
-  $config.read('method-prompt.txt', default: default_prompt) % {
+  $config_dir.read('method-prompt.txt', default: default_prompt) % {
     construct_type:, construct:, context:,
   }
 end
@@ -146,15 +150,18 @@ def build_class_module_prompt(construct_type, construct, context)
 
     Format requirements:
 
-    1. Focus on providing a description of the %{construct_type}'s purpose
+    1. focus on providing a description of the %{construct_type}'s purpose
        without including any code snippets.
-    2. Include @example tag if there are notable usage patterns for this
-       construct.
-    3. Never use `, `ruby, ```, ```ruby in your response.
-    4. Never add any other remarks or explanation to your response.
-    5. Start each line of your comment with a single # character.
+    2. **always** output just the line comments starting each with a single #
+       character.
+    3. **never** output any executable ruby code like class or module
+       definitions, or method definitions or other code outside of such
+       comments.
+    4. you should omit the @raise if you are not sure.
+    5. never use `, `ruby, ```, ```ruby in your response.
+    6. never add any other remarks or explanation to your response.
   EOT
-  $config.read('class-module-prompt.txt', default: default_prompt) % {
+  $config_dir.read('class-module-prompt.txt', default: default_prompt) % {
     construct_type:, construct:, context:,
   }
 end
@@ -171,7 +178,9 @@ def build_prompt(construct_type, construct, context)
 end
 
 filename_linenumber = ARGV.shift or fail "require file_name as second argument"
-$config             = Utils::ConfigDir.new('code_comment', env_var: 'XDG_CONFIG_HOME')
+$config = Utils::ConfigFile.new
+$config.configure_from_paths
+$config_dir             = Utils::ConfigDir.new('code_comment', env_var: 'XDG_CONFIG_HOME')
 base_url            = ENV['OLLAMA_URL'] || 'http://%s' % ENV.fetch('OLLAMA_HOST')
 model               = ENV.fetch('OLLAMA_MODEL', 'llama3.1')
 construct, construct_type = fetch_construct(filename_linenumber)
@@ -185,15 +194,17 @@ default_context = ContextSpook.generate_context do
     file "README.md", tags: %w[ documentation ]
 
     # Auto-discover files using globs
-    %w[ lib spec test ].each do |dir|
+    $config.code_comment.code_globs.each do |dir_glob|
+      dir = dir_glob.sub(%r(/.*), '').full? || 'none'
       namespace dir do
-        Dir["#{dir}/**/*.rb"].each do |filename|
-          file filename, tags: %w[ ruby ]
+        Dir[dir_glob].each do |filename|
+          file filename
         end
       end
     end
   end
 end
+
 context = if File.exist?(context_filename)
             STDERR.puts "Using context from #{context_filename.inspect}."
             ContextSpook.generate_context(context_filename)
@@ -223,7 +234,7 @@ default_system = <<~EOT
     * @example usage patterns when helpful
     * Avoid version information (@since)
 EOT
-system = $config.read('system.txt', default: default_system)
+system = $config_dir.read('system.txt', default: default_system)
 
 prompt = build_prompt(construct_type, construct, context)
 
@@ -238,10 +249,10 @@ default_options = JSON(
   min_p: 0.1,
 )
 
-client_config = Client::Config.load_from_json $config + 'client.json'
+client_config = Client::Config.load_from_json $config_dir + 'client.json'
 client_config.base_url = base_url
 ollama  = Client.configure_with(client_config)
-options = JSON.parse($config.read('options.json', default: default_options))
+options = JSON.parse($config_dir.read('options.json', default: default_options))
 
 if ENV['DEBUG'].to_i == 1
   File.open('debug.log', ?w) do |log|

data/bin/yaml_check

@@ -24,6 +24,8 @@
 #   DEBUG=1 ./yaml_check data.yaml
 #
 
+require 'yaml'
+
 format = -> s {
   if /^\((?<f>[^)]+)\):\ (?<m>.*?) at line (?<l>\d+) column (?<c>\d+)/ =~ s
     [ f, l, c, m ] * ?:

data/lib/utils/config_dir.rb

@@ -2,6 +2,21 @@ require 'pathname'
 require 'stringio'
 
 module Utils
+  # A configuration directory manager that handles path resolution and file
+  # operations within a specified directory structure.
+  #
+  # This class provides functionality for managing configuration directories by
+  # deriving paths based on a root directory and name, and offering methods to
+  # read files with optional default values and block handling. It supports
+  # environment variable-based root path resolution and uses Pathname for
+  # robust path manipulation.
+  #
+  # @example
+  #   config_dir = Utils::ConfigDir.new('myapp')
+  #   config_dir.to_s # => returns the string representation of the configuration directory path
+  #   config_dir.join('config.txt') # => returns a Pathname object for the joined path
+  #   config_dir.read('settings.rb') # => reads and returns the content of 'settings.rb' or nil if not found
+  #   config_dir.read('missing.txt', default: 'default content') # => returns 'default content' if file is missing
   class ConfigDir
     # Initializes a new ConfigDir instance with the specified name and optional
     # root path or environment variable.

data/lib/utils/config_file.rb

@@ -1,5 +1,11 @@
 require 'tins'
 
+# Configuration file manager for Utils library.
+#
+# This class provides functionality for loading, parsing, and managing
+# configuration settings from multiple sources. It supports DSL-style
+# configuration blocks and integrates with various utility components to
+# provide centralized configuration management.
 class Utils::ConfigFile
   class << self
     attr_accessor :config_file_paths
@@ -12,6 +18,12 @@ class Utils::ConfigFile
 
   include DSLKit::Interpreter
 
+  # Error raised when configuration file parsing fails.
+  #
+  # This exception is specifically designed to be thrown when issues occur
+  # during the parsing or processing of configuration files within the Utils
+  # library. It inherits from StandardError, making it a standard Ruby
+  # exception that can be caught and handled appropriately by calling code.
   class ConfigFileError < StandardError; end
 
   # The initialize method sets up a new instance of the class.
@@ -76,6 +88,12 @@ class Utils::ConfigFile
     self
   end
 
+  # Base class for defining configuration blocks with DSL accessors.
+  #
+  # This class provides a foundation for creating configuration classes that
+  # support dynamic attribute definition through DSL-style accessor methods. It
+  # includes functionality for registering configuration settings and
+  # generating Ruby code representations of the configuration state.
   class BlockConfig
     class << self
       # The inherited method extends the module with DSL accessor functionality
@@ -158,11 +176,17 @@ class Utils::ConfigFile
     end
   end
 
+  # A configuration class for test execution settings.
+  #
+  # This class manages the configuration options related to running tests,
+  # specifically supporting different test frameworks and defining which
+  # directories should be included in test discovery and execution.
   class Probe < BlockConfig
     # The config method sets up a configuration option for the test framework.
     #
     # This method defines a configuration parameter that specifies which test
-    # framework should be used, allowing for flexible test execution environments.
+    # framework should be used, allowing for flexible test execution
+    # environments.
     #
     # @param name [ Symbol ] the name of the configuration option
     # @param value [ Object ] the value to set for the configuration option
@@ -221,6 +245,13 @@ class Utils::ConfigFile
     @probe ||= Probe.new
   end
 
+  # A configuration class for file system operations.
+  #
+  # This class manages the configuration settings for searching and discovering
+  # files and directories while filtering out unwanted entries based on
+  # configured patterns. It provides functionality to define which directories
+  # should be pruned and which files should be skipped during file system
+  # operations.
   class FileFinder < BlockConfig
     # The prune? method checks if a basename matches any of the configured
     # prune directories.
@@ -254,6 +285,13 @@ class Utils::ConfigFile
     end
   end
 
+  # A configuration class for search operations.
+  #
+  # This class manages the configuration settings for searching files and
+  # directories while filtering out unwanted entries based on configured
+  # patterns. It inherits from FileFinder and provides functionality to define
+  # which directories should be pruned and which files should be skipped during
+  # search processes.
   class Search < FileFinder
     # The prune_dirs method configures the pattern for identifying directories
     # to be pruned during file system operations.
@@ -299,6 +337,12 @@ class Utils::ConfigFile
     @search ||= Search.new
   end
 
+  # A configuration class for file discovery operations.
+  #
+  # This class manages the configuration settings for discovering files and directories
+  # while filtering out unwanted entries based on configured patterns. It inherits from
+  # FileFinder and provides functionality to define which directories should be pruned
+  # and which files should be skipped during discovery processes.
   class Discover < FileFinder
     # The prune_dirs method configures the pattern for identifying directories
     # to be pruned during file system operations.
@@ -361,6 +405,13 @@ class Utils::ConfigFile
     @discover ||= Discover.new
   end
 
+  # A configuration class for file system scope operations.
+  #
+  # This class manages the configuration settings for defining which files and
+  # directories should be included or excluded during file system traversals
+  # and searches. It inherits from FileFinder and provides pattern matching
+  # capabilities for pruning directories and skipping specific files based on
+  # configured regular expressions.
   class Scope < FileFinder
     # The prune_dirs method configures the pattern for identifying directories
     # to be pruned during file system operations.
@@ -404,6 +455,12 @@ class Utils::ConfigFile
     @scope ||= Scope.new
   end
 
+  # A configuration class for whitespace handling operations.
+  #
+  # This class manages the configuration options related to removing or modifying
+  # trailing whitespace in files. It provides functionality to define patterns for
+  # pruning directories and skipping specific files during whitespace processing,
+  # ensuring that only relevant files are affected by space-stripping operations.
   class StripSpaces < FileFinder
     # The prune_dirs method configures the pattern for directory names that
     # should be pruned.
@@ -448,6 +505,12 @@ class Utils::ConfigFile
     @strip_spaces ||= StripSpaces.new
   end
 
+  # SSH tunnel configuration manager
+  #
+  # Provides functionality for configuring and managing SSH tunnels with support for
+  # different terminal multiplexers like tmux and screen. Allows setting up tunnel
+  # specifications with local and remote address/port combinations, handling
+  # environment variables, and managing copy/paste functionality for tunnel sessions.
   class SshTunnel < BlockConfig
     # The terminal_multiplexer method configures the terminal multiplexer
     # setting.
@@ -472,8 +535,6 @@ class Utils::ConfigFile
 
     # The initialize method sets up the instance by calling the superclass
     # constructor and assigning the terminal multiplexer configuration.
-    #
-    # @param terminal_multiplexer [ Object ] the terminal multiplexer to be assigned
     def initialize
       super
       self.terminal_multiplexer = terminal_multiplexer
@@ -540,6 +601,12 @@ class Utils::ConfigFile
       end
     end
 
+    # Manages the copy/paste functionality configuration for SSH tunnels.
+    #
+    # This class handles the setup and configuration of copy/paste capabilities
+    # within SSH tunnel sessions, allowing users to define network addresses,
+    # ports, and other parameters needed for establishing and managing
+    # copy/paste connections through SSH tunnels.
     class CopyPaste < BlockConfig
       # The bind_address method configures the network address to which the
       # server will bind for incoming connections.
@@ -614,6 +681,17 @@ class Utils::ConfigFile
     self.config_settings << :copy_paste
   end
 
+  # The ssh_tunnel method provides access to an SSH tunnel configuration instance.
+  #
+  # This method returns the existing SSH tunnel configuration object if one has
+  # already been created, or initializes and returns a new SSH tunnel
+  # configuration instance if no instance exists. If a block is provided, it
+  # will be passed to the SSH tunnel configuration constructor when creating a
+  # new instance.
+  #
+  # @param block [ Proc ] optional block to configure the SSH tunnel object
+  #
+  # @return [ Utils::ConfigFile::SshTunnel ] an SSH tunnel configuration instance
   def ssh_tunnel(&block)
     if block
       @ssh_tunnel = SshTunnel.new(&block)
@@ -621,6 +699,12 @@ class Utils::ConfigFile
     @ssh_tunnel ||= SshTunnel.new
   end
 
+  # A configuration class for editor settings.
+  #
+  # This class manages the configuration options related to editing operations,
+  # specifically focusing on Vim editor integration. It provides functionality
+  # to configure the path to the Vim executable and default arguments used when
+  # invoking the editor.
   class Edit < BlockConfig
     # The vim_path method determines the path to the vim executable.
     #
@@ -650,6 +734,12 @@ class Utils::ConfigFile
     @edit ||= Edit.new
   end
 
+  # A configuration class for file classification settings.
+  #
+  # This class manages the configuration options related to classifying files
+  # by type or category. It provides functionality to define path shifting
+  # behavior and prefix handling for determining how file paths should be
+  # categorized during classification operations.
   class Classify < BlockConfig
     # The shift_path_by_default method configuration accessor
     #
@@ -687,6 +777,12 @@ class Utils::ConfigFile
     @classify ||= Classify.new
   end
 
+  # A configuration class for directory synchronization settings.
+  #
+  # This class manages the configuration options related to synchronizing
+  # directories using rsync. It provides functionality to define patterns for
+  # skipping certain paths during synchronization operations, making it easy to
+  # exclude temporary, cache, or version control files from being synced.
   class SyncDir < BlockConfig
     # The skip_path method configures a regular expression pattern for skipping
     # paths.
@@ -730,6 +826,33 @@ class Utils::ConfigFile
     @sync_dir ||= SyncDir.new
   end
 
+  # A configuration class for code comment settings.
+  #
+  # This class manages the configuration options related to generating YARD
+  # documentation for Ruby source code. It provides access to glob patterns
+  # that define which files should be considered when generating code comments.
+  class CodeComment < BlockConfig
+    dsl_accessor :code_globs, 'lib/**/*.rb', 'spec/**/*.rb', 'tests/**/*rb'
+  end
+
+  # The code_comment method provides access to a CodeComment configuration
+  # instance.
+  #
+  # This method returns the existing CodeComment instance if one has already
+  # been created, or initializes and returns a new CodeComment instance if no
+  # instance exists. If a block is provided, it will be passed to the
+  # CodeComment constructor when creating a new instance.
+  #
+  # @param block [ Proc ] optional block to configure the CodeComment object
+  #
+  # @return [ Utils::ConfigFile::CodeComment ] a CodeComment configuration instance
+  def code_comment(&block)
+    if block
+      @code_comment = CodeComment.new(&block)
+    end
+    @code_comment ||= CodeComment.new
+  end
+
   # The to_ruby method generates a Ruby configuration string by collecting
   # configuration data from various components and combining them into a
   # single formatted output.

data/lib/utils/editor.rb

@@ -3,6 +3,19 @@ require 'rbconfig'
 require 'pstree'
 
 module Utils
+  # An editor interface for interacting with Vim server instances.
+  #
+  # This class provides functionality for managing Vim editor sessions through
+  # server connections, enabling features like remote file editing, window
+  # management, and server state monitoring. It handles communication with
+  # running Vim instances and supports various configuration options for
+  # customizing the editing experience.
+  #
+  # @example
+  #   editor = Utils::Editor.new
+  #   editor.edit('file.rb')
+  #   editor.activate
+  #   editor.stop
   class Editor
     # The initialize method sets up a new editor instance with default
     # configuration.
@@ -11,7 +24,8 @@ module Utils
     # flag, pause duration, and server name. It also loads the configuration
     # file and assigns the edit configuration section to the instance.
     #
-    # @param block [ Proc ] optional block to be executed after initialization
+    # @yield |editor| optional block to be executed after initialization with
+    # self as argument.
     #
     # @return [ Utils::Editor ] a new editor instance configured with default settings
     def initialize
@@ -41,10 +55,14 @@ module Utils
       name.upcase
     end
 
-    # The pause_duration method gets or sets the pause duration value.
+    # The pause_duration method provides access to the duration value used for
+    # pausing operations.
     #
-    # @return [ Integer ] the current pause duration value
-    # @param value [ Integer ] the new pause duration value to set
+    # This method returns the current value of the pause duration attribute,
+    # which controls how long certain operations should wait or pause between
+    # actions.
+    #
+    # @return [ Integer, Float ] the current pause duration value in seconds
     attr_accessor :pause_duration
 
     # The wait method gets the wait status.

data/lib/utils/finder.rb

@@ -4,6 +4,18 @@ require 'digest/md5'
 require 'fileutils'
 require 'mize'
 
+# A class for finding and searching files with configurable patterns and
+# filters.
+#
+# This class provides functionality for traversing file systems to locate files
+# based on various criteria including file extensions, directory pruning, and
+# pattern matching. It supports both indexed and direct search approaches to
+# optimize performance when dealing with large codebases or frequently accessed
+# file sets.
+#
+# @example
+#   finder = Utils::Finder.new(args: { l: true }, roots: ['.'])
+#   finder.search
 class Utils::Finder
   include Tins::Find
   include Utils::Patterns

data/lib/utils/grepper.rb

@@ -1,10 +1,27 @@
 require 'term/ansicolor'
 
+# A class for searching and matching text patterns within files.
+#
+# This class provides functionality to search through file systems for content
+# matching specified patterns, with support for various output formats and
+# filtering options. It handles directory pruning, file skipping, and different
+# types of pattern matching including regular expressions and fuzzy matching.
+#
+# @example
+#   grepper = Utils::Grepper.new(args: { l: true }, roots: ['.'])
+#   grepper.search
 class Utils::Grepper
   include Tins::Find
   include Utils::Patterns
   include Term::ANSIColor
 
+  # A queue implementation with size limitation.
+  #
+  # @example queue = Utils::Grepper::Queue.new(5) queue << "item1" queue <<
+  # "item2" # ... queue.data # => [ "item1", "item2", ... ]
+  #
+  # The Queue class provides a fixed-size buffer for storing objects. When the
+  # maximum size is exceeded, the oldest item is automatically removed.
   class Queue
     # The initialize method sets up a new instance with the specified maximum
     # size and empty data array.

data/lib/utils/irb.rb

@@ -9,7 +9,19 @@ $editor = Utils::Editor.new
 $pager = ENV['PAGER'] || 'less -r'
 
 module Utils
+  # A module that extends Ruby's core classes with additional utility methods
+  # for interactive development.
+  #
+  # Provides enhanced functionality for IRB sessions through method extensions
+  # on Object, String, and Regexp classes. Includes features like improved
+  # pattern matching, shell command integration, file I/O operations,
+  # performance measurement tools, and developer productivity enhancements.
   module IRB
+    # A module that extends Regexp functionality with additional pattern
+    # matching and display capabilities.
+    #
+    # Provides enhanced regexp operations including match highlighting and
+    # shell command integration.
     module Shell
       require 'fileutils'
       include FileUtils
@@ -223,6 +235,12 @@ module Utils
         end.compact.sort!
       end
 
+      # Base class for wrapping objects with descriptive metadata.
+      #
+      # This class provides a foundation for creating wrapper objects that
+      # associate descriptive information with underlying objects. It handles
+      # name conversion and provides common methods for accessing and comparing
+      # wrapped objects.
       class WrapperBase
         include Comparable
 
@@ -293,6 +311,15 @@ module Utils
         end
       end
 
+      # A wrapper class for Ruby method objects that provides enhanced
+      # introspection and display capabilities.
+      #
+      # This class extends WrapperBase to create specialized wrappers for Ruby
+      # method objects, offering detailed information about methods including
+      # their source location, arity, and owner. It facilitates interactive
+      # exploration of Ruby methods in environments like IRB by providing
+      # structured access to method metadata and enabling sorting and
+      # comparison operations based on method descriptions.
       class MethodWrapper < WrapperBase
         # The initialize method sets up a new instance with the specified
         # object, method name, and module flag.
@@ -356,6 +383,15 @@ module Utils
         end
       end
 
+      # A wrapper class for Ruby constant objects that provides enhanced
+      # introspection and display capabilities.
+      #
+      # This class extends WrapperBase to create specialized wrappers for Ruby
+      # constant objects, offering detailed information about constants
+      # including their names and associated classes. It facilitates
+      # interactive exploration of Ruby constants in environments like IRB by
+      # providing structured access to constant metadata and enabling sorting
+      # and comparison operations based on constant descriptions.
       class ConstantWrapper < WrapperBase
         # The initialize method sets up a new instance with the provided object
         # and name.
@@ -667,6 +703,15 @@ module Utils
       end
     end
 
+    # A module that extends Regexp functionality with additional pattern
+    # matching and display capabilities.
+    #
+    # Provides enhanced regexp operations including match highlighting and
+    # shell command integration.
+    #
+    # @example
+    #   /pattern/ # => regular expression object
+    #   /pattern/.show_match("text") # => highlighted text match
     module Regexp
       # The show_match method evaluates a string against the receiver pattern
       # and highlights matching portions.
@@ -691,6 +736,11 @@ module Utils
       end
     end
 
+    # A module that extends String with additional utility methods for shell
+    # command piping and file writing operations.
+    #
+    # Provides convenient methods for executing shell commands on string
+    # content and securely writing strings to files.
     module String
       # The | method executes a shell command and returns its output.
       #

data/lib/utils/line_blamer.rb

@@ -1,4 +1,12 @@
 module Utils
+  # A class for analyzing and retrieving git blame information for specific
+  # lines of code.
+  #
+  # This class provides functionality to initialize with a file path and line
+  # number, and then perform git blame operations to obtain information about
+  # when and by whom that specific line was last modified. It serves as a
+  # utility for developers to quickly access historical context for individual
+  # lines of code within their projects.
   class LineBlamer
     # Initializes a new LineBlamer instance to analyze source code line
     # information.

data/lib/utils/md5.rb

@@ -1,6 +1,12 @@
 require 'digest/md5'
 
 module Utils
+  # MD5 module for computing MD5 hash digests of files.
+  #
+  # This module provides functionality for calculating MD5 hash digests of
+  # files using the Digest::MD5 library. It offers a convenient interface for
+  # computing hashes while handling file reading in chunks to optimize memory
+  # usage during the hashing process.
   module MD5
     class << self
       # The buffer_size accessor method provides read and write access to the

data/lib/utils/patterns.rb

@@ -1,5 +1,19 @@
 module Utils
+  # A module that provides pattern matching functionality for file searching
+  # and text processing.
+  #
+  # It includes classes for different types of pattern matching including fuzzy
+  # matching and regular expression matching.
   module Patterns
+
+    # Base class for pattern matching implementations.
+    #
+    # This class serves as the foundation for various pattern matching
+    # strategies, providing common functionality for initializing patterns with
+    # character set filtering and case sensitivity options. It handles the core
+    # configuration and delegates specific matching behavior to subclasses.
+    #
+    # @abstract
     class Pattern
       # Initializes a new Pattern instance with the specified options.
       #
@@ -46,6 +60,19 @@ module Utils
       end
     end
 
+    # A fuzzy pattern matcher that performs partial string matching while
+    # preserving character order.
+    #
+    # This class implements a pattern matching strategy that allows for
+    # flexible matching of strings where the characters of the search pattern
+    # appear in sequence within the target string, but not necessarily
+    # consecutively. It is particularly useful for finding text patterns with
+    # potential typos or
+    # when only partial information about the target is available.
+    #
+    # @example
+    #   fuzzy_pattern = FuzzyPattern.new(pattern: 'abc')
+    #   fuzzy_pattern.match('a1b2c3') # => matches because 'a', 'b', and 'c' appear in order
     class FuzzyPattern < Pattern
       # Initializes a fuzzy pattern matcher by processing the pattern string
       # and compiling it into a regular expression.
@@ -70,6 +97,18 @@ module Utils
       end
     end
 
+    # A regular expression pattern matcher that performs exact string matching
+    # with optional case sensitivity.
+    #
+    # This class extends the base Pattern class to provide functionality for
+    # creating and using regular expression patterns. It compiles the provided
+    # pattern into a Regexp object that can be used for matching operations
+    # throughout the application. The pattern matching behavior is influenced
+    # by the case sensitivity configuration inherited from the parent class.
+    #
+    # @example
+    #   regexp_pattern = RegexpPattern.new(pattern: 'foo', icase: true)
+    #   regexp_pattern.match('FOO') # => matches because case insensitive
     class RegexpPattern < Pattern
       # Initializes a regular expression pattern matcher with the specified
       # options.

data/lib/utils/probe_server.rb

@@ -2,6 +2,12 @@ require 'unix_socks'
 require 'term/ansicolor'
 
 module Utils
+  # A process job representation for execution within the probe server system.
+  #
+  # This class encapsulates the information and behavior associated with a
+  # single executable task that can be enqueued and processed by a ProbeServer.
+  # It holds command arguments, manages execution status, and provides
+  # mechanisms for serialization and display of job information.
   class ProcessJob
     include Term::ANSIColor
 
@@ -125,7 +131,19 @@ module Utils
     end
   end
 
+  # A client for interacting with the probe server through Unix domain sockets.
+  #
+  # This class provides an interface for enqueueing process jobs and managing
+  # environment variables on a remote probe server. It uses Unix domain sockets
+  # to communicate with the server, enabling distributed task execution and
+  # configuration management.
   class ProbeClient
+    # A proxy class for managing environment variables through a probe server communication channel.
+    #
+    # This class provides a wrapper around the ENV object that allows setting and retrieving
+    # environment variables while logging these operations through the probe server.
+    # It intercepts assignments and lookups to provide visibility into environment modifications
+    # during probe server operations.
     class EnvProxy
       # The initialize method sets up a new instance with the provided server
       # object.
@@ -208,6 +226,13 @@ module Utils
     end
   end
 
+  # A probe server for managing and executing process jobs through Unix domain
+  # sockets.
+  #
+  # This class provides a mechanism for enqueueing and running process jobs in
+  # a distributed manner, using Unix domain sockets for communication. It
+  # maintains a queue of jobs, tracks their execution status, and provides an
+  # interactive interface for managing the server.
   class ProbeServer
     include Term::ANSIColor
 
@@ -276,13 +301,13 @@ module Utils
 
     annotate :shortcut
 
+    doc 'Display this help.'
+    shortcut :h
     # The help method displays a formatted list of available commands and their
     # descriptions.
     #
     # This method organizes and presents the documented commands along with their
     # shortcuts and descriptions in a formatted table layout for easy reference.
-    doc 'Display this help.'
-    shortcut :h
     def help
       docs      = doc_annotations.sort_by(&:first)
       docs_size = docs.map { |a| a.first.size }.max
@@ -295,6 +320,8 @@ module Utils
       }
     end
 
+    doc 'Enqueue a new job with the argument array <args>.'
+    shortcut :e
     # The job_enqueue method adds a new process job to the execution queue.
     #
     # This method creates a process job instance with the provided arguments
@@ -302,8 +329,6 @@ module Utils
     # about the enqueued job through output messaging.
     #
     # @param args [ Array ] the command arguments to be executed by the process job
-    doc 'Enqueue a new job with the argument array <args>.'
-    shortcut :e
     def job_enqueue(args)
       job = ProcessJob.new(args:, probe_server: self)
       output_message " → #{job.inspect} enqueued.", type: :info
@@ -311,17 +336,19 @@ module Utils
     end
     alias enqueue job_enqueue
 
+    doc 'Quit the server.'
+    shortcut :q
     # The shutdown method terminates the probe server process immediately.
     #
     # This method outputs a warning message indicating that the server is being
     # shut down forcefully and then exits the program with status code 23.
-    doc 'Quit the server.'
-    shortcut :q
     def shutdown
       output_message "Server was shutdown down manually!", type: :info
       exit 23
     end
 
+    doc 'Repeat the job with <job_id> or the last, it will be assigned a new id, though.'
+    shortcut :r
     # The job_repeat method re-executes a previously run job from the history.
     #
     # This method takes a job identifier and attempts to find the corresponding
@@ -334,8 +361,6 @@ module Utils
     #
     # @return [ TrueClass, FalseClass ] true if the job was found and re-enqueued,
     #         false otherwise
-    doc 'Repeat the job with <job_id> or the last, it will be assigned a new id, though.'
-    shortcut :r
     def job_repeat(job_id = @history.last)
       ProcessJob === job_id and job_id = job_id.id
       if old_job = @history.find { |job| job.id == job_id }
@@ -346,17 +371,18 @@ module Utils
       end
     end
 
+    doc 'List the history of run jobs.'
+    shortcut :l
     # The history_list method displays the list of previously executed jobs
     # from the server's history.
     #
     # This method outputs all completed jobs that have been processed by the probe server,
     # showing their identifiers and command arguments for review.
-    doc 'List the history of run jobs.'
-    shortcut :l
     def history_list
       output_message @history
     end
 
+    doc 'Clear the history of run jobs.'
     # The history_clear method clears all entries from the server's execution
     # history.
     #
@@ -365,12 +391,18 @@ module Utils
     # probe server.
     #
     # @return [ TrueClass ] always returns true after clearing the history
-    doc 'Clear the history of run jobs.'
     def history_clear
       @history = []
       true
     end
 
+    # A wrapper class for environment variable management that logs operations.
+    #
+    # This class provides a transparent interface for accessing and modifying
+    # environment variables while recording these interactions. It delegates all
+    # method calls to an underlying object (typically ENV) but intercepts assignments
+    # to log the changes, enabling tracking of environment modifications during
+    # probe server operations.
     class LogWrapper < BasicObject
       # The initialize method sets up a new instance with the provided server
       # object and object.

data/lib/utils/ssh_tunnel_specification.rb

@@ -1,4 +1,19 @@
 module Utils
+  # A class that represents an SSH tunnel specification for configuring network
+  # connections.
+  #
+  # This class parses and stores the configuration details for SSH tunnels,
+  # including local and remote address/port combinations. It provides methods
+  # to validate the specification, convert it to string or array
+  # representations, and access individual components of the tunnel
+  # configuration.
+  #
+  # @example
+  #   spec = Utils::SshTunnelSpecification.new('localhost:8080:remote.host:22')
+  #   spec.local_addr  # => 'localhost'
+  #   spec.local_port  # => 8080
+  #   spec.remote_addr # => 'remote.host'
+  #   spec.remote_port # => 22
   class SshTunnelSpecification
     # Initializes a new SshTunnelSpecification instance by parsing the provided
     # specification string.

data/lib/utils/version.rb

@@ -1,6 +1,6 @@
 module Utils
   # Utils version
-  VERSION         = '0.73.1'
+  VERSION         = '0.74.0'
   VERSION_ARRAY   = VERSION.split('.').map(&:to_i) # :nodoc:
   VERSION_MAJOR   = VERSION_ARRAY[0] # :nodoc:
   VERSION_MINOR   = VERSION_ARRAY[1] # :nodoc:

data/lib/utils/xt/source_location_extension.rb

@@ -1,5 +1,23 @@
 module Utils
+  # Extension module for adding source location functionality to objects.
+  #
+  # This module provides enhanced source location capabilities by extending
+  # objects with methods that can determine file paths and line numbers
+  # associated with method definitions, class references, or file-based
+  # locations. It supports parsing of various input formats including file:line
+  # syntax, class.method patterns, and provides convenient accessors for
+  # filename, line number, and range information through the source_location
+  # method.
   module Xt
+    # Extension module for adding source location functionality to objects.
+    #
+    # This module provides enhanced source location capabilities by extending
+    # objects with methods that can determine file paths and line numbers
+    # associated with method definitions, class references, or file-based
+    # locations. It supports parsing of various input formats including
+    # file:line syntax, class.method patterns, and provides convenient
+    # accessors for filename, line number, and range information through the
+    # source_location method.
     module SourceLocationExtension
       # Regular expression to match Ruby class method signatures
       # Matches patterns like "ClassName#method" or "ClassName.method"

data/lib/utils.rb

@@ -1,5 +1,11 @@
 require 'tins/xt'
 
+# The main Utils module serves as the primary namespace for the developer
+# productivity command-line utilities gem.
+
+# This module provides the core functionality and organization for the Utils
+# library, which delivers a curated collection of command-line tools designed
+# to streamline software development workflows and automate repetitive tasks.
 module Utils
   require 'utils/version'
   require 'utils/md5'

data/utils.gemspec

@@ -1,9 +1,9 @@
 # -*- encoding: utf-8 -*-
-# stub: utils 0.73.1 ruby lib
+# stub: utils 0.74.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "utils".freeze
-  s.version = "0.73.1".freeze
+  s.version = "0.74.0".freeze
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]
@@ -23,7 +23,7 @@ Gem::Specification.new do |s|
 
   s.specification_version = 4
 
-  s.add_development_dependency(%q<gem_hadar>.freeze, ["~> 2.0".freeze])
+  s.add_development_dependency(%q<gem_hadar>.freeze, ["~> 2.1".freeze])
   s.add_development_dependency(%q<test-unit>.freeze, [">= 0".freeze])
   s.add_runtime_dependency(%q<unix_socks>.freeze, [">= 0".freeze])
   s.add_runtime_dependency(%q<webrick>.freeze, [">= 0".freeze])

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: utils
 version: !ruby/object:Gem::Version
-  version: 0.73.1
+  version: 0.74.0
 platform: ruby
 authors:
 - Florian Frank
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '2.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '2.1'
 - !ruby/object:Gem::Dependency
   name: test-unit
   requirement: !ruby/object:Gem::Requirement