utils 0.68.0 → 0.70.0

data/bin/code_comment

@@ -1,15 +1,73 @@
 #!/usr/bin/env ruby
+#
+# Generate YARD comments for Ruby methods using LLM assistance
+#
+# Usage:
+#   code_comment path/to/file.rb:line_number # Generate comment for method at line
+#
+# This script analyzes Ruby source code and generates high-quality YARD comments
+# for methods using an LLM (via Ollama). It examines the surrounding context to
+# identify method definitions and provides comprehensive documentation including
+# descriptions, parameters, return values, and exceptions.
+#
+# Requires:
+#   - Git repository with Ruby files in lib/, spec/, or test/ directories
+#   - Ollama server running locally or accessible via OLLAMA_URL / OLLAMA_HOST
+#   - Configuration files in ~/.config/code_comment/
+#     - system.txt: System prompt for LLM
+#     - prompt.txt: Template for comment generation
+#     - client.json: Ollama client settings
+#     - options.json: Generation options (temperature, etc.)
+#
+# Environment variables:
+#   OLLAMA_URL: Base URL of Ollama server
+#   OLLAMA_MODEL: Model to use (default: llama3.1)
+#   XDG_CONFIG_HOME: Custom config directory location
+#   DEBUG: Set to 1 for verbose output and debug.log creation
+#
+# Examples:
+#   code_comment app/models/user.rb:42      # Document method at line 42
+#   code_comment lib/api/client.rb:15       # Document method at line 15
 
 require 'ollama'
 include Ollama
 require 'utils'
-include Utils::XDGConfig
 
-def fetch_method(filename_linenumber)
+META_METHOD = /(
+  (class_)?                   # Optional "class_" prefix
+  attr(                       # "attr" keyword
+    _reader|                  # reader variant
+    _writer|                  # writer variant  
+    _accessor                 # accessor variant
+  )?                          # Optional variant
+  |                           # OR
+  dsl_(accessor|reader)       # DSL accessor patterns
+  |                           # OR
+  constant                    # Constant definitions
+  |                           # OR
+  config                      # config settings
+  |                           # OR
+  (instance_)?                # Optional "instance_" prefix
+  thread(                     # "thread" keyword
+    _local|                    # local variant
+    _global                   # global variant
+  )?                          # Optional variant
+)\s+:/x
+
+def fetch_construct(filename_linenumber)
   result = ''
   source_location = filename_linenumber.source_location
   lf = Tins::LinesFile.for_filename(source_location.filename, source_location.linenumber)
-  if spaces = lf.match_backward(/^(\s*|.*?(private|protected)\s+)def\s+(?:\S+?)(?:\(|\s*$)/)&.first
+  if /^(?:\s*)(class|module)/ =~ lf.line
+    return lf.line, $1.to_sym
+  end
+  if /^(?:\s*)(?:[A-Z]\w*)\s*=\s*(Class|Module)\.new/ =~ lf.line
+    return lf.line, $1.downcase.to_sym
+  end
+  if lf.line =~ META_METHOD
+    return lf.line, :method
+  end
+  if spaces = lf.match_backward(/^(\s*?)(\S.*?\s+)?def\s+/)&.first
     line_number_begin = lf.line_number
     lf.match_forward(/^#{spaces}end/)
     line_number_end = lf.line_number
@@ -18,137 +76,134 @@ def fetch_method(filename_linenumber)
       result << lf.line
     end
   end
-  result
+  return result, :method
 end
 
-def fetch_file(filename_linenumber)
-  source_location = filename_linenumber.source_location
-  File.read(source_location.filename)
+def build_method_prompt(construct_type, construct, file_contents)
+  default_prompt = <<~EOT
+    Look at this code to document it:
+
+    %{file_contents}
+
+    Here's an example for how you should document a %{construct_type}.
+
+      # The foo %{construct_type} computes the bar result by processing…
+      # then it returns the result.
+      #
+      # @param first [ String ] the foo string
+      # @param second [ Integer ] the number of bars lengthy detailed mutltiline
+      #                           detailed explanation including a newline.
+      # @param third [ TrueClass, FalseClass ]
+      #
+      # @yield [ a, b ]
+      #
+      # @raise [ ArgumentError ] if block argument wasn't provided
+      # @raise [ ArgumentError ] if second parameter was too small.
+      #
+      # @return [ ProcessResult ]
+
+    And this is the %{construct_type} you should document:
+
+    %{construct}
+
+    Output a YARD comment for this %{construct_type}:
+
+    Format requirements:
+
+    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.
+  EOT
+  $config.read('method-prompt.txt', default: default_prompt) % {
+    construct_type:, construct:, file_contents:,
+  }
 end
 
-filename_linenumber = ARGV.shift or fail "require file_name as second argument"
-method              = fetch_method(filename_linenumber)
-method_indent       = method[/\A( *)/, 1].size
-#file                = fetch_file(filename_linenumber)
-files               = Dir['{lib,spec,test}/**/*.rb']
-base_url            = ENV['OLLAMA_URL'] || 'http://%s' % ENV.fetch('OLLAMA_HOST')
-model               = ENV.fetch('OLLAMA_MODEL', 'llama3.1')
-#file                = File.read(file_name)
-#call_sites          = %x(cscope -L -3 "#{method_name}" $(find . -name '*.rb') | awk '{ print $1 ":" $3 }').lines.map(&:chomp).uniq
-#methods             = call_sites.map { fetch_method(_1) } * ?\n
+def build_class_module_prompt(construct_type, construct, file_contents)
+  default_prompt = <<~EOT
+    Look at this code to document it:
 
-cheatsheet = <<EOT
-Documenting Code with YARD
+    %{file_contents}
 
-By default, YARD is compatible with the same RDoc syntax most Ruby developers
-are already familiar with. However, one of the biggest advantages of YARD is
-the extended meta-data syntax, commonly known as "tags", that you can use to
-express small bits of information in a structured and formal manner. While RDoc
-syntax expects you to describe your method in a completely free-form manner,
-YARD recommends declaring your parameters, return types, etc. with the @tag
-syntax, which makes outputting the documentation more consistent and easier to
-read. Consider the RDoc documentation for a method to_format:
+    Here's an example for how you should document a %{construct_type}.
 
-# Converts the object into textual markup given a specific `format`
-# (defaults to `:html`)
-#
-# == Parameters:
-# format::
-#   A Symbol declaring the format to convert the object to. This
-#   can be `:text` or `:html`.
-#
-# == Returns:
-# A string representing the object in a specified
-# format.
-#
-def to_format(format = :html)
-  # format the object
-end
+      # A brief description of what this %{construct_type} does.
+      #
+      # @example
+      #   MyClass.new do |obj|
+      #     obj.method
+      #   end
 
-While this may seem easy enough to read and understand, it's hard for a machine
-to properly pull this data back out of our documentation. Also we've tied our
-markup to our content, and now our documentation becomes hard to maintain if we
-decide later to change our markup style (maybe we don't want the ":" suffix on
-our headers anymore).
+    And this is the %{construct_type} you should document:
 
-In YARD, we would simply define our method as:
+    %{construct}
 
-# Converts the object into textual markup given a specific format.
-#
-# @param format [Symbol] the format type, `:text` or `:html`
-# @return [String] the object converted into the expected format.
-# @raise [CannotFormatException] the object cannot be formatted
-def to_format(format = :html)
-  # format the object
-end
+    Output a YARD comment for this %{construct_type}:
 
-Using tags we can add semantic metadata to our code without worrying about
-presentation. YARD will handle presentation for us when we decide to generate
-documentation later.
-EOT
+    Format requirements:
 
-system = <<EOT
-Provide high-quality YARD comments for the given Ruby method, including a brief
-description of its purpose, parameters, raised exceptions (and why), and
-return values, assuming an expert-level understanding of the programming
-concepts involved.
-EOT
-system = nil
-
-prompt = <<EOT
-Look at this code to document it:
-
-#{files.map { File.read(_1) } * ?\n}
-
-Here's an example for how you should document a method.
-
-    # The foo method computes the bar result by processing…
-    # then it returns the result.
-    #
-    # @param first [ String ] the foo string
-    # @param second [ Integer ] the number of bars lengthy detailed mutltiline
-    #                           detailed explanation including a newline.
-    # @param third [ TrueClass, FalseClass ]
-    #
-    # @yield [ a, b ]
-    #
-    # @raise [ ArgumentError ] if block argument wasn't provided
-    # @raise [ ArgumentError ] if second parameter was too small.
-    #
-    # @example
-    #   bar.foo("blub", 4) { |a, b| … } #=> …
-    #
-    # @return [ ProcessResult ]
-    def foo(first, second, third: false, &block)
-      block or raise ArgumentError, 'no &block'
-      a = first * 2
-      if second < 0
-        raise ArgumentError, 'too small'
-      end
-      b = "foo" * second
-      if third
-        a = a * b
-      end
-      block_result = block.(a, b)
-      result = process block_result
-      return result
-    end
+    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.
+  EOT
+  $config.read('class-module-prompt.txt', default: default_prompt) % {
+    construct_type:, construct:, file_contents:,
+  }
+end
 
-And this is the method you should document:
+def build_prompt(construct_type, construct, file_contents)
+  case construct_type
+  when :method
+    build_method_prompt(construct_type, construct, file_contents)
+  when :class, :module
+    build_class_module_prompt(construct_type, construct, file_contents)
+  else
+    fail "unknown construct_type #{construct_type.inspect}"
+  end
+end
 
-#{method}
+filename_linenumber = ARGV.shift or fail "require file_name as second argument"
+$config             = Utils::ConfigDir.new('code_comment', env_var: 'XDG_CONFIG_HOME')
+files               = Dir['{lib,spec,test}/**/*.rb']
+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)
+construct_indent          = construct[/\A( *)/, 1].size
+file_contents = files.map { _1 + ":\n" + File.read(_1) } * ?\n
+#call_sites          = %x(cscope -L -3 "#{method_name}" $(find . -name '*.rb') | awk '{ print $1 ":" $3 }').lines.map(&:chomp).uniq
+#methods             = call_sites.map { fetch_method(_1) } * ?\n
+
+default_system = <<~EOT
+  **Guidelines**
 
-Output a YARD comment for this method:
+  - When answering, assume an expert-level understanding of the programming
+  concepts involved.
 
-Format requirements:
+  - If given a **method**, provide high-quality YARD comments including:
+    * A brief description of its purpose
+    * Parameter documentation (@param)
+    * Return value documentation (@return)
+    * Exception documentation (@raise) when appropriate
+    * Avoid version information (@since)
 
-1. Focus on providing a description of the method's purpose, without including any code snippets.
-2. Never use `, `ruby, ```, ```ruby in your response.
-3. Never add any other remarks or explanation to your response.
-4. Start each line of your comment with a single # character.
+  - If given a **class or module**, provide high-quality YARD comments including:
+    * A brief description of its purpose
+    * Public interface documentation
+    * @example usage patterns when helpful
+    * Avoid version information (@since)
 EOT
+system = $config.read('system.txt', default: default_system)
 
-options = Ollama::Options.new(
+prompt = build_prompt(construct_type, construct, file_contents)
+
+default_options = JSON(
   #repeat_penalty: 1.8,
   num_ctx: 16384,
   num_predict: 512,
@@ -159,6 +214,11 @@ options = Ollama::Options.new(
   min_p: 0.1,
 )
 
+client_config = Client::Config.load_from_json $config + 'client.json'
+client_config.base_url = base_url
+ollama  = Client.configure_with(client_config)
+options = JSON.parse($config.read('options.json', default: default_options))
+
 if ENV['DEBUG'].to_i == 1
   File.open('debug.log', ?w) do |log|
     log.puts "system:\n#{system}"
@@ -168,9 +228,5 @@ if ENV['DEBUG'].to_i == 1
   end
 end
 
-config = xdg_config('code_comment')
-client_config = Client::Config.load_from_json "#{config}/client.json"
-client_config.base_url = base_url
-ollama   = Client.configure_with(client_config)
 response = ollama.generate(model:, system:, prompt:, options:, stream: false, think: false).response
-puts response.gsub(/^/) { ' ' * method_indent }
+puts response.gsub(/^/) { ' ' * construct_indent }

data/bin/commit_message

@@ -1,9 +1,33 @@
 #!/usr/bin/env ruby
+#
+# Git Commit Message Generator
+#
+# Generates AI-powered commit messages based on git changes using Ollama.
+# Reads configuration from $XDG_CONFIG_HOME/commit_message/ directory.
+#
+# Usage:
+#   commit_message
+#
+# The script automatically:
+# - Determines current git branch name
+# - Loads configuration files (client.json, options.json, system.txt, prompt.txt)
+# - Generates commit message using ollama_cli with the current diff as input
+#
+# Requirements:
+# - Git repository in current directory
+# - ollama_cli tool installed
+# - Ollama server running
+# - Configuration files in $XDG_CONFIG_HOME/commit_message/
+#
+# Configuration files:
+# - client.json: Ollama API client configuration
+# - options.json: Generation options  
+# - system.txt: System prompt for AI model
+# - prompt.txt: Commit message template, contains %{branch} and %{stdin}
 
 require 'utils'
-include Utils::XDGConfig
 
-config = xdg_config('commit_message')
+config = Utils::ConfigDir.new('commit_message', env_var: 'XDG_CONFIG_HOME')
 
 branch = `git rev-parse --abbrev-ref HEAD`.chomp
 exec 'ollama_cli', '-c', "#{config}/client.json",

data/bin/create_cstags

@@ -1,4 +1,22 @@
 #!/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'

data/bin/create_tags

@@ -1,4 +1,14 @@
 #!/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'
 

data/bin/discover

@@ -1,13 +1,43 @@
 #!/usr/bin/env ruby
+#
+# File Discovery and Search Tool
+#
+# Interactive file discovery and search utility with advanced filtering and
+# editing capabilities. Combines file system traversal with intelligent pattern
+# matching and Vim integration.
+#
+# Features:
+# - Interactive pattern input with live search results
+# - File system discovery with directory traversal
+# - Vim integration for editing discovered files
+# - Configurable search filters (regexp, fuzzy, case-insensitive)
+# - Search index management and caching
+# - Directory listing and leaf directory identification
+# - Character set filtering for patterns
+# - Interactive selection when multiple matches exist
+#
+# The tool creates a searchable index of your file system (which is also used
+# by the search tool) and provides interactive discovery of files matching your
+# criteria, with seamless Vim
+# integration.
 
 require 'utils'
 include Utils
-require 'tins/xt'
 include Tins::GO
 require 'search_ui'
 include SearchUI
 require 'pathname'
 
+# The edit_files method opens editor windows for specified file paths.
+#
+# This method allows users to edit one or more files using the configured
+# editor. It provides options to pick a specific file from multiple paths or
+# edit all files directly. The method supports waiting for the editor process
+# to complete before returning control.
+#
+# @param paths [ Array<String> ] the file paths to be edited
+# @param pick [ TrueClass, FalseClass ] whether to prompt for file selection
+# @param wait [ TrueClass, FalseClass ] whether to wait for the editor to finish
 def edit_files(*paths, pick: false, wait: true)
   editor = Utils::Editor.new
   if pick
@@ -25,6 +55,13 @@ def edit_files(*paths, pick: false, wait: true)
   end
 end
 
+# The usage method displays the help message and version information for the
+# application.
+#
+# This method prints a formatted usage message to standard output, including
+# the application name, available options, and version number. It also shows
+# detailed descriptions of each command-line option and their expected
+# arguments.
 def usage
   puts <<-EOT
 Usage: #{File.basename($0)} [OPTS] [PATTERN] [PATHS]

data/bin/edit

@@ -1,4 +1,10 @@
 #!/usr/bin/env ruby
+#
+# Enhanced vim editor launcher with advanced feature
+# 
+# This script is a sophisticated wrapper around vim that provides enhanced
+# editing capabilities including server management, git integration, and
+# batch file handling.
 
 require 'tins/xt'
 include Tins::GO
@@ -6,6 +12,13 @@ require 'utils'
 include Utils
 require 'tempfile'
 
+# The usage method displays the command-line interface help text and version
+# information.
+#
+# This method outputs a formatted help message that describes the available
+# options and usage patterns for the command-line tool, including detailed
+# explanations of each flag and their purposes. It also displays the current
+# version of the tool.
 def usage
   puts <<-EOT
 Usage: #{File.basename($0)} [OPTS] [PATHS]
@@ -49,7 +62,7 @@ if $opt[?l]
 elsif $opt[?s]
   begin
     until STDIN.eof?
-      line = STDIN.gets
+      line = STDIN.gets.chomp
       line = line.sub(/.*?([^:\s]+:)/, '\1')
       editor.edit(line)
     end

data/bin/edit_wait

@@ -1,3 +1,17 @@
 #!/usr/bin/env ruby
+#
+# Wait for editor to close files before returning control
+#
+# Usage:
+#   edit_wait file1 file2    # Wait for editor to close specified files
+#
+# This script is a simple wrapper that calls 'edit -w' with all provided arguments.
+# The '-w' flag makes the editor wait until the file(s) are closed before returning.
+#
+#
+# Examples:
+#   edit_wait README.md            # Edit README.md and wait for closure
+#   edit_wait file1.txt file2.txt  # Edit multiple files and wait for all to close
+
 
 exec 'edit', '-w', *$*