utils 0.73.1 → 0.75.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eeb8c50e8895ed05192b62c4c7c86d0f5eccd34234e6878233c5324542c2c5ef
-  data.tar.gz: f0c4adb49862333e4c85fba3ccde54c1a899dffb23a0cd846123d4bcc6ee7fa8
+  metadata.gz: 6f4bbd1ff8f20adf6d2f9876330c263ddf9108bd2d46ceb68e45211c5b8fbea7
+  data.tar.gz: cad94f08ffcd2b55eed18ab9ce7e0f9b44a6efe6162a0655b1e70da24bd1327e
 SHA512:
-  metadata.gz: 18e205eb300082bdd1341083a63ac508c80e3af31faabcbe4675ec4c2c7c3c7b5975e1479ec426aba98ebadad3dc2d8e66b0b351aeae092eb525a1caf23ff1a7
-  data.tar.gz: 8c3f8ec933935f36b4d79e5224dd49e71f5839bc152969f528b459f19240e743089ff7234e17eb644d6e19dda511eb8fdcf1a58e05cb4278752f831a9d87e5dd
+  metadata.gz: 3e8abfc5598071b791206ead4d6dd2efe1cdf344e880521ffe020f0a360cb36f1801a64f879c9d29687096afae2c19dd4d9291a050c1b59b66c9616238e3594b
+  data.tar.gz: 730dfcd09cceadd29734c36f7f02c2937c7053e9d74ff5df302dae3e522fabc5cd674eede9d90311fe86aa43cfd18dde5a8dfa957d002fc1c8f9125f23290dd1

data/.utilsrc

@@ -1,12 +1,12 @@
 # vim: set ft=ruby:
 
 search do
-  prune_dirs /\A(\.svn|\.git|\.terraform|CVS|tmp|coverage|corpus|pkg|\.yardoc)\z/
+  prune_dirs /\A(\.svn|\.git|\.terraform|CVS|tmp|coverage|corpus|pkg|\.yardoc|doc)\z/
   skip_files /(\A\.|\.sw[pon]\z|\.(log|fnm|jpg|jpeg|png|pdf|svg)\z|\Atags\z|~\z)/i
 end
 
 discover do
-  prune_dirs /\A(\.svn|\.git|\.terraform|\.yardoc|CVS|tmp|coverage|corpus|pkg|\.yardoc)\z/
+  prune_dirs /\A(\.svn|\.git|\.terraform|\.yardoc|CVS|tmp|coverage|corpus|pkg|\.yardoc|doc)\z/
   skip_files /(\A\.|\.sw[pon]\z|\.log\z|~\z)/
   index_expire_after 3_600
 end
@@ -31,3 +31,7 @@ end
 classify do
   shift_path_by_default 1
 end
+
+code_indexer do
+  verbose true
+end

data/Rakefile

@@ -14,7 +14,8 @@ 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', 
+    'cscope.out', '.starscope.db'
   package_ignore '.gitignore', 'VERSION'
   readme      'README.md'
   licenses << 'GPL-2.0'
@@ -31,6 +32,7 @@ GemHadar do
   dependency 'ollama-ruby',    '~> 1.6'
   dependency 'kramdown-ansi',  '~> 0.1'
   dependency 'figlet',         '~> 1.0'
+  dependency 'starscope'
   dependency 'context_spook',  '~> 0.2'
   dependency 'simplecov'
   dependency 'debug'

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
@@ -113,12 +113,18 @@ def build_method_prompt(construct_type, construct, context)
 
     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 blank lines between comment lines that belong to the
+       same logical section
+    4. **Never** output any executable ruby code like class or module
+       definitions, or method definitions or other code outside of such
+       comments.
+    5. You should omit the @raise if you are not sure.
+    6. **Never** use `, `ruby, ```, ```ruby in your response.
+    7. **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
@@ -148,13 +154,18 @@ def build_class_module_prompt(construct_type, construct, context)
 
     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 blank lines between comment lines that belong to the
+       same logical section
+    4. **Never** output any executable ruby code like class or module
+       definitions, or method definitions or other code outside of such
+       comments.
+    5. You should omit the @raise if you are not sure.
+    6. **Never** use `, `ruby, ```, ```ruby in your response.
+    7. **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 +182,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 +198,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 +238,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 +253,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/code_indexer

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+
+require 'utils'
+config = Utils::ConfigFile.new
+config.configure_from_paths
+
+config.code_indexer.formats.each do |format, output|
+  paths = config.code_indexer.paths.grep_v(/Resolving dependencies/)
+  puts "Indexing code for #{format}…"
+  cmd = [ 'starscope', '-e', format, '-f', output, '--no-read' ]
+  config.code_indexer.verbose and cmd << '--verbose'
+  cmd.push(*paths)
+  system(*cmd)
+  puts "Done."
+end

data/bin/serve

@@ -6,7 +6,7 @@ require 'tins/go'
 include Tins::GO
 require 'webrick'
 
-$opts = go 'p:h'
+$opts = go 'b:p:h', defaults: { ?b => '127.0.0.1', ?p => 8888 }
 
 if $opts[?h]
   puts <<~USAGE
@@ -15,12 +15,14 @@ if $opts[?h]
     Usage: #{File.basename($0)} [OPTIONS] [DIR]
     
     Options:
-      -p PORT    Specify port number (default: 8888)
-      -h         Show this help message
+      -b ADDRESS  Address to bind to  (default: "127.0.0.1")
+      -p PORT     Specify port number (default: 8888)
+      -h          Show this help message
     
     Examples:
-      #{File.basename($0)}                    # Serve current directory on port 8888
-      #{File.basename($0)} -p 3000            # Serve on port 3000
+      #{File.basename($0)}                    # Serve current directory on 127.0.0.1:8888
+      #{File.basename($0)} -b 0.0.0.0         # Serve on 0.0.0.0:3000
+      #{File.basename($0)} -p 3000            # Serve on 127.0.0.1:3000
       #{File.basename($0)} /path/to/dir       # Serve specific directory
     
     Note: If no directory is specified, serves the current working directory.
@@ -28,11 +30,13 @@ if $opts[?h]
   exit
 end
 
-port = ($opts[?p] || 8888).to_i
+address = $opts[?b]
+port    = $opts[?p].to_i
 s = WEBrick::HTTPServer.new(
+  BindAddress:  address,
   Port:         port,
   DocumentRoot: ARGV.shift || Dir.pwd
 )
 trap('INT') { s.shutdown }
-puts "You have been served: http://localhost:#{port}/"
+puts "You have been served: http://#{address}:#{port}/"
 s.start

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,49 +405,61 @@ class Utils::ConfigFile
     @discover ||= Discover.new
   end
 
-  class Scope < FileFinder
-    # The prune_dirs method configures the pattern for identifying directories
-    # to be pruned during file system operations.
-    #
-    # This method sets up a regular expression pattern that matches directory
-    # names which should be excluded from processing. The default pattern
-    # excludes version control directories (.svn, .git, CVS) and temporary
-    # directories (tmp).
-    #
-    # @param first [ Regexp ] the regular expression pattern for matching directories to prune
-    config :prune_dirs, /\A(\.svn|\.git|CVS|tmp)\z/
+  # A configuration class for code indexing operations.
+  #
+  # This class manages the configuration settings for generating code indexes
+  # like ctags and cscope. It provides functionality to define which paths
+  # should be indexed and what file formats should be generated for each
+  # indexing tool.
+  #
+  # @example
+  #   indexer = Utils::ConfigFile.new.code_indexer do |config|
+  #     config.paths = %w[ lib spec ]
+  #     config.formats = { 'ctags' => 'tags', 'cscope' => 'cscope.out' }
+  #   end
+  #
+  # The paths config configures the directories to be included in the index
+  # generation process.
+  #
+  # The formats config configures the output file formats for different indexing
+  # tools and the output filenames.
+  class CodeIndexer < BlockConfig
+    config :verbose, false
 
-    # The skip_files configuration method sets up a regular expression pattern
-    # for filtering out files based on their names.
-    #
-    # This method configures a pattern that matches filenames which should be
-    # skipped during file processing operations.
-    # It uses a regular expression to identify files that start with a dot, end
-    # with common temporary file extensions, or match other patterns typically
-    # associated with backup, swap, log, or temporary files.
-    #
-    # @param pattern [ Regexp ] the regular expression pattern used to identify files to skip
-    config :skip_files, /(\A\.|\.sw[pon]\z|\.log\z|~\z)/
+    config :paths, %w[ bin lib spec tests ]
+
+    config :formats, {
+      'ctags'  => 'tags',
+      'cscope' => 'cscope.out',
+    }
   end
 
-  # The scope method initializes and returns a Scope object.
+  # The code_indexer method manages and returns a CodeIndexer configuration
+  # instance.
   #
-  # This method creates a new Scope instance either from the provided block or
-  # with default initialization if no block is given.
-  # The scope object is stored as an instance variable and reused on subsequent
-  # calls.
+  # This method provides access to a CodeIndexer object that handles configuration
+  # for generating code indexes such as ctags and cscope files. It ensures that only
+  # one CodeIndexer instance is created per object by storing it in an instance variable.
+  # When a block is provided, it initializes the CodeIndexer with custom settings;
+  # otherwise, it returns a default CodeIndexer instance.
   #
-  # @param block [ Proc ] optional block to pass to the Scope constructor
+  # @param block [ Proc ] optional block to configure the CodeIndexer object
   #
-  # @return [ Utils::Scope ] a Scope object configured with the provided block
-  # or default settings
-  def scope(&block)
+  # @return [ Utils::ConfigFile::CodeIndexer ] a CodeIndexer configuration instance
+  #         configured either by the block or with default settings
+  def code_indexer(&block)
     if block
-      @scope = Scope.new(&block)
+      @code_indexer = CodeIndexer.new(&block)
     end
-    @scope ||= Scope.new
+    @code_indexer ||= CodeIndexer.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 +504,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 +534,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 +600,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 +680,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 +698,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 +733,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 +776,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 +825,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.75.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.75.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "utils".freeze
-  s.version = "0.73.1".freeze
+  s.version = "0.75.0".freeze
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]
@@ -11,9 +11,9 @@ Gem::Specification.new do |s|
   s.date = "1980-01-02"
   s.description = "This ruby gem provides some useful command line utilities".freeze
   s.email = "flori@ping.de".freeze
-  s.executables = ["ascii7".freeze, "blameline".freeze, "changes".freeze, "classify".freeze, "code_comment".freeze, "commit_message".freeze, "create_cstags".freeze, "create_tags".freeze, "discover".freeze, "edit".freeze, "edit_wait".freeze, "enum".freeze, "git-empty".freeze, "git-versions".freeze, "json_check".freeze, "long_lines".freeze, "myex".freeze, "on_change".freeze, "path".freeze, "print_method".freeze, "probe".freeze, "rainbow".freeze, "rd2md".freeze, "search".freeze, "sedit".freeze, "serve".freeze, "ssh-tunnel".freeze, "strip_spaces".freeze, "sync_dir".freeze, "untest".freeze, "utils-utilsrc".freeze, "vcf2alias".freeze, "yaml_check".freeze]
+  s.executables = ["ascii7".freeze, "blameline".freeze, "changes".freeze, "classify".freeze, "code_comment".freeze, "code_indexer".freeze, "commit_message".freeze, "discover".freeze, "edit".freeze, "edit_wait".freeze, "enum".freeze, "git-empty".freeze, "git-versions".freeze, "json_check".freeze, "long_lines".freeze, "myex".freeze, "on_change".freeze, "path".freeze, "print_method".freeze, "probe".freeze, "rainbow".freeze, "rd2md".freeze, "search".freeze, "sedit".freeze, "serve".freeze, "ssh-tunnel".freeze, "strip_spaces".freeze, "sync_dir".freeze, "untest".freeze, "utils-utilsrc".freeze, "vcf2alias".freeze, "yaml_check".freeze]
   s.extra_rdoc_files = ["README.md".freeze, "lib/utils.rb".freeze, "lib/utils/config_dir.rb".freeze, "lib/utils/config_file.rb".freeze, "lib/utils/editor.rb".freeze, "lib/utils/finder.rb".freeze, "lib/utils/grepper.rb".freeze, "lib/utils/irb.rb".freeze, "lib/utils/line_blamer.rb".freeze, "lib/utils/line_formatter.rb".freeze, "lib/utils/md5.rb".freeze, "lib/utils/patterns.rb".freeze, "lib/utils/probe_server.rb".freeze, "lib/utils/ssh_tunnel_specification.rb".freeze, "lib/utils/version.rb".freeze, "lib/utils/xt/source_location_extension.rb".freeze]
-  s.files = [".github/dependabot.yml".freeze, ".github/workflows/codeql-analysis.yml".freeze, ".utilsrc".freeze, "Gemfile".freeze, "LICENSE".freeze, "README.md".freeze, "Rakefile".freeze, "bin/ascii7".freeze, "bin/blameline".freeze, "bin/changes".freeze, "bin/classify".freeze, "bin/code_comment".freeze, "bin/commit_message".freeze, "bin/create_cstags".freeze, "bin/create_tags".freeze, "bin/discover".freeze, "bin/edit".freeze, "bin/edit_wait".freeze, "bin/enum".freeze, "bin/git-empty".freeze, "bin/git-versions".freeze, "bin/json_check".freeze, "bin/long_lines".freeze, "bin/myex".freeze, "bin/on_change".freeze, "bin/path".freeze, "bin/print_method".freeze, "bin/probe".freeze, "bin/rainbow".freeze, "bin/rd2md".freeze, "bin/search".freeze, "bin/sedit".freeze, "bin/serve".freeze, "bin/ssh-tunnel".freeze, "bin/strip_spaces".freeze, "bin/sync_dir".freeze, "bin/untest".freeze, "bin/utils-utilsrc".freeze, "bin/vcf2alias".freeze, "bin/yaml_check".freeze, "lib/utils.rb".freeze, "lib/utils/config_dir.rb".freeze, "lib/utils/config_file.rb".freeze, "lib/utils/editor.rb".freeze, "lib/utils/finder.rb".freeze, "lib/utils/grepper.rb".freeze, "lib/utils/irb.rb".freeze, "lib/utils/line_blamer.rb".freeze, "lib/utils/line_formatter.rb".freeze, "lib/utils/md5.rb".freeze, "lib/utils/patterns.rb".freeze, "lib/utils/probe_server.rb".freeze, "lib/utils/ssh_tunnel_specification.rb".freeze, "lib/utils/version.rb".freeze, "lib/utils/xt/source_location_extension.rb".freeze, "tests/test_helper.rb".freeze, "tests/utils_test.rb".freeze, "utils.gemspec".freeze]
+  s.files = [".github/dependabot.yml".freeze, ".github/workflows/codeql-analysis.yml".freeze, ".utilsrc".freeze, "Gemfile".freeze, "LICENSE".freeze, "README.md".freeze, "Rakefile".freeze, "bin/ascii7".freeze, "bin/blameline".freeze, "bin/changes".freeze, "bin/classify".freeze, "bin/code_comment".freeze, "bin/code_indexer".freeze, "bin/commit_message".freeze, "bin/discover".freeze, "bin/edit".freeze, "bin/edit_wait".freeze, "bin/enum".freeze, "bin/git-empty".freeze, "bin/git-versions".freeze, "bin/json_check".freeze, "bin/long_lines".freeze, "bin/myex".freeze, "bin/on_change".freeze, "bin/path".freeze, "bin/print_method".freeze, "bin/probe".freeze, "bin/rainbow".freeze, "bin/rd2md".freeze, "bin/search".freeze, "bin/sedit".freeze, "bin/serve".freeze, "bin/ssh-tunnel".freeze, "bin/strip_spaces".freeze, "bin/sync_dir".freeze, "bin/untest".freeze, "bin/utils-utilsrc".freeze, "bin/vcf2alias".freeze, "bin/yaml_check".freeze, "lib/utils.rb".freeze, "lib/utils/config_dir.rb".freeze, "lib/utils/config_file.rb".freeze, "lib/utils/editor.rb".freeze, "lib/utils/finder.rb".freeze, "lib/utils/grepper.rb".freeze, "lib/utils/irb.rb".freeze, "lib/utils/line_blamer.rb".freeze, "lib/utils/line_formatter.rb".freeze, "lib/utils/md5.rb".freeze, "lib/utils/patterns.rb".freeze, "lib/utils/probe_server.rb".freeze, "lib/utils/ssh_tunnel_specification.rb".freeze, "lib/utils/version.rb".freeze, "lib/utils/xt/source_location_extension.rb".freeze, "tests/test_helper.rb".freeze, "tests/utils_test.rb".freeze, "utils.gemspec".freeze]
   s.homepage = "http://github.com/flori/utils".freeze
   s.licenses = ["GPL-2.0".freeze]
   s.rdoc_options = ["--title".freeze, "Utils - Some useful command line utilities".freeze, "--main".freeze, "README.md".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.2".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])
@@ -37,6 +37,7 @@ Gem::Specification.new do |s|
   s.add_runtime_dependency(%q<ollama-ruby>.freeze, ["~> 1.6".freeze])
   s.add_runtime_dependency(%q<kramdown-ansi>.freeze, ["~> 0.1".freeze])
   s.add_runtime_dependency(%q<figlet>.freeze, ["~> 1.0".freeze])
+  s.add_runtime_dependency(%q<starscope>.freeze, [">= 0".freeze])
   s.add_runtime_dependency(%q<context_spook>.freeze, ["~> 0.2".freeze])
   s.add_runtime_dependency(%q<simplecov>.freeze, [">= 0".freeze])
   s.add_runtime_dependency(%q<debug>.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.75.0
 platform: ruby
 authors:
 - Florian Frank
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '2.2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '2.2'
 - !ruby/object:Gem::Dependency
   name: test-unit
   requirement: !ruby/object:Gem::Requirement
@@ -205,6 +205,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: starscope
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: context_spook
   requirement: !ruby/object:Gem::Requirement
@@ -255,9 +269,8 @@ executables:
 - changes
 - classify
 - code_comment
+- code_indexer
 - commit_message
-- create_cstags
-- create_tags
 - discover
 - edit
 - edit_wait
@@ -314,9 +327,8 @@ files:
 - bin/changes
 - bin/classify
 - bin/code_comment
+- bin/code_indexer
 - bin/commit_message
-- bin/create_cstags
-- bin/create_tags
 - bin/discover
 - bin/edit
 - bin/edit_wait

data/bin/create_cstags

@@ -1,48 +0,0 @@
-#!/usr/bin/env ruby
-#
-# Create cscope database for project files
-#
-# Usage:
-#   create_cstags    # Generate cscope.out database in current directory
-#
-# This script generates a cscope database (cscope.out) by collecting all
-# project files and building an index for efficient cross-reference searching.
-# It uses bundle paths and project roots to determine which files to include.
-#
-# Requires:
-#   - cscope command-line tool
-#
-# The script will:
-#   1. Collect all files from project roots (including bundle paths)
-#   2. Generate cscope.out database with cross-references
-#   3. Show progress using infobar visualization
-#   4. Report the size of the created database
-
-require 'utils'
-require 'infobar'
-
-config = Utils::ConfigFile.new
-config.configure_from_paths
-
-roots = %w[ . ] + `bundle list --paths`.lines.map(&:chomp)
-
-IO.popen('cscope 2>/dev/null -R -b -i - -f cscope.out', 'w') do |scope|
-  finder = Utils::Finder.new(
-    pattern: '',
-    roots:   roots,
-    config:  config,
-  )
-  finder.search.paths.with_infobar(label: 'Collecting files') do |path|
-    scope.puts path
-    +infobar
-  end
-
-  infobar.newline
-  Infobar.busy(label: 'Creating cstags', frames: :braille7) do
-    scope.close
-  end
-end
-
-if megabytes = File.size('cscope.out').to_f / 1024 ** 2 rescue nil
-  infobar.puts 'Created %.3fM of cstags.' % megabytes
-end

data/bin/create_tags

@@ -1,20 +0,0 @@
-#!/usr/bin/env ruby
-# 
-# Creates ctags index for Ruby project including bundled gems
-#
-# This script generates a tags file that enables code navigation in editors
-# like Vim. It automatically includes:
-# - Current directory (.) 
-# - All gem paths from bundle list
-# - Excludes pkg directory to avoid vendor code
-#
-# Usage: Run directly from project root
-
-require 'infobar'
-
-paths = %w[ . ] + `bundle list --paths`.lines.map(&:chomp)
-cmd = %w[ ctags --recurse=yes --exclude=pkg --languages=Ruby,C ] + paths
-Infobar.busy(label: 'Creating tags', frames: :braille7) { system(*cmd) }
-if megabytes = File.size('tags').to_f / 1024 ** 2 rescue nil
-  infobar.puts 'Created %.3fM of tags.' % megabytes
-end