gem_hadar 1.24.0 → 1.26.0

data/lib/gem_hadar.rb

@@ -25,12 +25,16 @@ require_maybe 'rspec/core/rake_task'
 class GemHadar
 end
 require 'gem_hadar/version'
+require 'gem_hadar/utils'
 require 'gem_hadar/setup'
 require 'gem_hadar/template_compiler'
 require 'gem_hadar/github'
+require 'gem_hadar/prompt_template'
 
 class GemHadar
   include Term::ANSIColor
+  include GemHadar::Utils
+  include GemHadar::PromptTemplate
 
   if defined?(::RbConfig)
     include ::RbConfig
@@ -47,6 +51,12 @@ class GemHadar
     block and instance_eval(&block)
   end
 
+  # The has_to_be_set method raises an error if a required gem configuration
+  # attribute is not set.
+  #
+  # @param name [ String ] the name of the required attribute
+  #
+  # @raise [ ArgumentError ] if the specified attribute has not been set
   def has_to_be_set(name)
     fail "#{self.class}: #{name} has to be set for gem"
   end
@@ -130,7 +140,7 @@ class GemHadar
   end
 
   dsl_accessor :yard_dir do
-    'yard'
+    'doc'
   end
 
   dsl_accessor :extensions do FileList['ext/**/extconf.rb'] end
@@ -178,6 +188,18 @@ class GemHadar
     dsl_accessor :gemset do @outer_scope.name end
   end
 
+  # The rvm method configures RVM (Ruby Version Manager) settings for the gem
+  # project.
+  #
+  # This method initializes and returns an RvmConfig object that holds RVM-specific
+  # configuration such as the Ruby version to use and the gemset name.
+  # If a block is provided, it configures the RvmConfig object with the given
+  # settings. If no block is provided and no existing RvmConfig object exists,
+  # it creates a new one with default settings.
+  #
+  # @param block [ Proc ] optional block to configure RVM settings
+  #
+  # @return [ GemHadar::RvmConfig ] the RVM configuration object
   def rvm(&block)
     if block
       @rvm = RvmConfig.new(&block)
@@ -189,6 +211,12 @@ class GemHadar
 
   dsl_accessor :default_task_dependencies, [ :gemspec, :test ]
 
+  # The default_task method defines the default Rake task for the gem project.
+  #
+  # This method sets up a Rake task named :default that depends on the tasks
+  # specified in the default_task_dependencies accessor. It provides a convenient
+  # way to run the most common or essential tasks for the project with a single
+  # command.
   def default_task
     desc 'Default task'
     task :default => default_task_dependencies
@@ -196,11 +224,26 @@ class GemHadar
 
   dsl_accessor :build_task_dependencies, [ :clobber, :gemspec, :package, :'version:tag' ]
 
+  # The build_task method defines a Rake task that orchestrates the complete
+  # build process for packaging the gem.
+  #
+  # This method sets up a :build task that depends on the tasks specified in
+  # the build_task_dependencies accessor. It provides a convenient way to
+  # execute all necessary steps for building packages for a release with a
+  # single command.
   def build_task
     desc 'Build task (builds all packages for a release)'
     task :build => build_task_dependencies
   end
 
+  # The install_library method sets up a Rake task for installing the library
+  # or executable into site_ruby directories.
+  #
+  # This method configures an :install task that depends on the
+  # :prepare_install task and executes the provided block. It stores the block
+  # in an instance variable to be called later when the task is executed.
+  #
+  # @param block [ Proc ] the block containing the installation logic
   def install_library(&block)
     @install_library_block = -> do
       desc 'Install executable/library into site_ruby directories'
@@ -208,6 +251,15 @@ class GemHadar
     end
   end
 
+  # The clean method manages the CLEAN file list for Rake tasks.
+  #
+  # When called without arguments, it returns the current CLEAN file list.
+  # When called with arguments, it adds the specified files to the CLEAN list.
+  #
+  # @param args [ Array<String> ] optional list of files to add to the CLEAN list
+  #
+  # @return [ FileList, nil ] the CLEAN file list when no arguments provided,
+  #                           nil otherwise
   def clean(*args)
     if args.empty?
       CLEAN
@@ -216,6 +268,15 @@ class GemHadar
     end
   end
 
+  # The clobber method manages the CLOBBER file list for Rake tasks.
+  #
+  # When called without arguments, it returns the current CLOBBER file list.
+  # When called with arguments, it adds the specified files to the CLOBBER list.
+  #
+  # @param args [ Array<String> ] optional list of files to add to the CLOBBER list
+  #
+  # @return [ FileList, nil ] the CLOBBER file list when no arguments provided,
+  #                           nil otherwise
   def clobber(*args)
     if args.empty?
       CLOBBER
@@ -224,6 +285,15 @@ class GemHadar
     end
   end
 
+  # The ignore method manages the list of files to be ignored by the gem.
+  #
+  # When called without arguments, it returns the current set of ignored files.
+  # When called with arguments, it adds the specified files to the ignore list.
+  #
+  # @param args [ Array<String> ] optional list of file patterns to add to the ignore list
+  #
+  # @return [ Set<String>, nil ] the set of ignored files when no arguments provided,
+  #                           nil otherwise
   def ignore(*args)
     if args.empty?
       ignore_files
@@ -232,6 +302,17 @@ class GemHadar
     end
   end
 
+  # The package_ignore method manages the list of files to be ignored during
+  # gem packaging.
+  #
+  # When called without arguments, it returns the current set of package ignore
+  # files. When called with arguments, it adds the specified file patterns to
+  # the package ignore list.
+  #
+  # @param args [ Array<String> ] optional list of file patterns to add to the package ignore list
+  #
+  # @return [ Set<String>, nil ] the set of package ignore files when no arguments provided,
+  #                           nil otherwise
   def package_ignore(*args)
     if args.empty?
       package_ignore_files
@@ -240,14 +321,28 @@ class GemHadar
     end
   end
 
+  # The dependency method adds a new runtime dependency to the gem.
+  #
+  # @param args [ Array ] the arguments defining the dependency
   def dependency(*args)
     @dependencies << args
   end
 
+  # The development_dependency method adds a new development-time dependency to
+  # the gem.
+  #
+  # @param args [ Array ] the arguments defining the development dependency
   def development_dependency(*args)
     @development_dependencies << args
   end
 
+  # The gems_install_task method defines a Rake task for installing all gem
+  # dependencies specified in the Gemfile.
+  #
+  # This method sets up a :gems:install task that executes a block to install
+  # gems. If no block is provided, it defaults to running 'bundle install'.
+  #
+  # @param block [ Proc ] optional block containing the installation command
   def gems_install_task(&block)
     block ||= proc {  sh 'bundle install' }
     desc 'Install all gems from the Gemfile'
@@ -256,6 +351,14 @@ class GemHadar
     end
   end
 
+  # The version_task method defines a Rake task that generates a version file
+  # for the gem.
+  #
+  # This method creates a task named :version that writes version information
+  # to a Ruby file in the lib directory. The generated file contains constants
+  # for the version and its components, as well as an optional epilogue
+  # section. The task ensures the target directory exists and uses secure file
+  # writing to prevent permission issues.
   def version_task
     desc m = "Writing version information for #{name}-#{version}"
     task :version do
@@ -277,6 +380,13 @@ class GemHadar
     end
   end
 
+  # The version_show_task method defines a Rake task that displays the current
+  # version of the gem.
+  #
+  # This method creates a :version:show task under the Rake namespace that
+  # reads the version from the generated version file in the lib directory and
+  # compares it with the version specified in the GemHadar configuration. It
+  # then outputs a message indicating whether the versions match or not.
   def version_show_task
     namespace :version do
       desc "Displaying the current version"
@@ -295,6 +405,21 @@ class GemHadar
     end
   end
 
+  # The version_log_diff method generates a git log output containing patch
+  # differences between two specified versions.
+  #
+  # This method retrieves the commit history between a starting version and an
+  # ending version, including detailed changes (patch format) for each commit.
+  # It supports comparing against the current HEAD or specific version tags,
+  # and automatically determines the appropriate previous version when only a
+  # target version is provided.
+  #
+  # @param to_version [ String ] the ending version tag or 'HEAD' to compare up to the latest commit
+  # @param from_version [ String, nil ] the starting version tag; if nil, it defaults based on to_version
+  #
+  # @raise [ RuntimeError ] if the specified version tags are not found in the repository
+  #
+  # @return [ String ] the git log output in patch format showing changes between the two versions
   def version_log_diff(to_version: 'HEAD', from_version: nil)
     if to_version == 'HEAD'
       if from_version.blank?
@@ -327,6 +452,15 @@ class GemHadar
     end
   end
 
+  # The version_diff_task method defines Rake tasks for listing and displaying
+  # git version differences.
+  #
+  # This method sets up two subtasks under the :version namespace:
+  #
+  # - A :list task that fetches all git tags, ensures the operation succeeds,
+  # and outputs the sorted list of versions.
+  # - A :diff task that calculates the version range, displays a colored diff
+  # between the versions, and shows the changes.
   def version_diff_task
     namespace :version do
       desc "List all versions in order"
@@ -338,19 +472,25 @@ class GemHadar
 
       desc "Displaying the diff from env var VERSION to the next version or HEAD"
       task :diff do
-        version_tags = versions.map { version_tag(_1) } + %w[ HEAD ]
-        found_version_tag = version_tags.index(version_tag(version))
-        found_version_tag.nil? and fail "cannot find version tag #{version_tag(version)}"
-        start_version, end_version = version_tags[found_version_tag, 2]
+        start_version, end_version = determine_version_range
         puts color(172) { "Showing diff from version %s to %s:" % [ start_version, end_version ] }
         puts `git diff --color=always #{start_version}..#{end_version}`
       end
     end
   end
 
+  # The gem_hadar_update_task method defines a Rake task that updates the
+  # gem_hadar dependency version in the gemspec file.
+  #
+  # This method creates a :gem_hadar:update task under the Rake namespace that
+  # prompts the user to specify a new gem_hadar version.
+  # It then reads the existing gemspec file, modifies the version constraint
+  # for the gem_hadar dependency, and writes the updated content back to the
+  # file. If the specified version is already present in the gemspec, it skips
+  # the update and notifies the user.
   def gem_hadar_update_task
     namespace :gem_hadar do
-      desc 'Update gem_hadar a different version'
+      desc 'Update gem_hadar to a different version'
       task :update do
         answer = ask?("Which gem_hadar version? ", /^((?:\d+.){2}(?:\d+))$/)
         unless answer
@@ -376,6 +516,14 @@ class GemHadar
     end
   end
 
+  # The gemspec_task method defines a Rake task that generates and writes a
+  # gemspec file for the project.
+  #
+  # This method creates a :gemspec task that depends on the :version task,
+  # ensuring the version is set before generating the gemspec. It constructs
+  # the filename based on the project name, displays a warning message
+  # indicating the file being written, and uses secure_write to create the
+  # gemspec file with content generated by the gemspec method.
   def gemspec_task
     desc 'Create a gemspec file'
     task :gemspec => :version do
@@ -385,6 +533,12 @@ class GemHadar
     end
   end
 
+  # The package_task method sets up a Rake task for packaging the gem.
+  #
+  # This method configures a task that creates a package directory, initializes
+  # a Gem::PackageTask with the current gem specification, and specifies that
+  # tar files should be created. It also includes the files to be packaged by
+  # adding gem_files to the package_files attribute of the Gem::PackageTask.
   def package_task
     clean 'pkg'
     Gem::PackageTask.new(gemspec) do |pkg|
@@ -393,24 +547,20 @@ class GemHadar
     end
   end
 
+  # The install_library_task method executes the installed library task block
+  # if it has been defined.
   def install_library_task
     @install_library_block.full?(:call)
   end
 
-  def doc_task
-    clean 'doc'
-    desc "Creating documentation"
-    task :doc do
-      sh 'yard doc'
-      cmd = 'yardoc'
-      if readme
-        cmd << " --readme '#{readme}'"
-      end
-      cmd << ' - ' << doc_files * ' '
-      sh cmd
-    end
-  end
-
+  # The test_task method sets up a Rake task for executing the project's test
+  # suite.
+  #
+  # This method configures a Rake task named :test that runs the test suite
+  # using Rake::TestTask. It includes the test directory and required paths in
+  # the load path, specifies the test files to run, and enables verbose output.
+  # The task also conditionally depends on the :compile task if project
+  # extensions are present.
   def test_task
     tt =  Rake::TestTask.new(:run_tests) do |t|
       t.libs << test_dir
@@ -422,6 +572,12 @@ class GemHadar
     task :test => [ (:compile if extensions.full?), tt.name ].compact
   end
 
+  # The spec_task method sets up a Rake task for executing RSpec tests.
+  #
+  # This method configures a :spec task that runs the project's RSpec test
+  # suite. It initializes an RSpec::Core::RakeTask with appropriate Ruby
+  # options, test pattern, and verbose output. The task also conditionally
+  # depends on the :compile task if project extensions are present.
   def spec_task
     defined? ::RSpec::Core::RakeTask or return
     st =  RSpec::Core::RakeTask.new(:run_specs) do |t|
@@ -433,6 +589,15 @@ class GemHadar
     task :spec => [ (:compile if extensions.full?), st.name ].compact
   end
 
+  # The rcov_task method sets up a Rake task for executing code coverage tests
+  # using RCov.
+  #
+  # This method configures a :rcov task that runs the project's test suite with
+  # RCov to generate code coverage reports. It includes the test directory and
+  # required paths in the load path, specifies the test files to run, and
+  # enables verbose output. The task also conditionally depends on the :compile
+  # task if project extensions are present. If RCov is not available, it
+  # displays a warning message suggesting to install RCov.
   def rcov_task
     if defined?(::Rcov)
       rt = ::Rcov::RcovTask.new(:run_rcov) do |t|
@@ -454,33 +619,76 @@ class GemHadar
     end
   end
 
+  # The version_bump_task method defines Rake tasks for incrementing the gem's
+  # version number.
+  #
+  # This method sets up a hierarchical task structure under the :version
+  # namespace:
+  #
+  # - It creates subtasks in the :version:bump namespace for explicitly bumping
+  # major, minor, or build versions.
+  # - It also defines a :version:bump task that automatically suggests the
+  # appropriate version bump type by analyzing recent changes using AI. The
+  # suggestion is based on the git log diff between the previous version and
+  # the current HEAD, and it prompts the user for confirmation before applying
+  # the bump.
+  #
+  # The tasks utilize the version_log_diff method to gather change information,
+  # the ollama_generate method to get AI-powered suggestions, and the
+  # version_bump_to method to perform the actual version update.
   def version_bump_task
     namespace :version do
       namespace :bump do
         desc 'Bump major version'
         task :major do
-          version = File.read('VERSION').chomp.version
-          version.bump(:major)
-          secure_write('VERSION') { |v| v.puts version }
+          version_bump_to(:major)
         end
 
         desc 'Bump minor version'
         task :minor do
-          version = File.read('VERSION').chomp.version
-          version.bump(:minor)
-          secure_write('VERSION') { |v| v.puts version }
+          version_bump_to(:minor)
         end
 
         desc 'Bump build version'
         task :build do
-          version = File.read('VERSION').chomp.version
-          version.bump(:build)
-          secure_write('VERSION') { |v| v.puts version }
+          version_bump_to(:build)
+        end
+      end
+
+      desc 'Bump version with AI suggestion'
+      task :bump do
+        log_diff = version_log_diff(from_version: nil, to_version: 'HEAD')
+        system   = xdg_config('version_bump_system_prompt.txt', default_version_bump_system_prompt)
+        prompt   = xdg_config('version_bump_prompt.txt', default_version_bump_prompt) % { version:, log_diff: }
+        response = ollama_generate(system:, prompt:)
+        puts response
+        default = nil
+        if response =~ /(major|minor|build)\s*$/
+          default = $1
+        end
+        response = ask?(
+          'Bump a major, minor, or build version%{default}? ',
+          /\A(major|minor|build)\z/,
+          default:
+        )
+        if version_type = response&.[](1)
+          version_bump_to(version_type)
+        else
+          exit 1
         end
       end
     end
   end
 
+  # The version_tag_task method defines a Rake task that creates a Git tag for
+  # the current version.
+  #
+  # This method sets up a :version:tag task under the Rake namespace that
+  # creates an annotated Git tag for the project's current version. It checks
+  # if a tag with the same name already exists and handles the case where the
+  # tag exists but is different from the current commit. If the tag already
+  # exists and is different, it prompts the user to confirm whether to
+  # overwrite it forcefully.
   def version_tag_task
     namespace :version do
       desc "Tag this commit as version #{version}"
@@ -505,10 +713,24 @@ class GemHadar
     end
   end
 
+  # The git_remote method retrieves the primary Git remote name configured for
+  # the project.
+  #
+  # It first checks the GIT_REMOTE environment variable for a custom remote
+  # specification. If not set, it defaults to 'origin'. When multiple remotes
+  # are specified in the environment variable, only the first one is returned.
   def git_remote
     ENV.fetch('GIT_REMOTE', 'origin').split(/\s+/).first
   end
 
+  # The master_prepare_task method defines a Rake task that sets up a remote
+  # Git repository for the project.
+  #
+  # This method creates a :master:prepare task under the Rake namespace that
+  # guides the user through creating a new bare Git repository on a remote
+  # server via SSH. It prompts for the remote name, directory path, and SSH
+  # account details to configure the repository and establish a connection back
+  # to the local project.
   def master_prepare_task
     namespace :master do
       desc "Prepare a remote git repository for this project"
@@ -526,6 +748,20 @@ class GemHadar
     end
   end
 
+  # The version_push_task method defines Rake tasks for pushing version tags to
+  # Git remotes.
+  #
+  # This method sets up a hierarchical task structure under the :version
+  # namespace:
+  #
+  # - It creates subtasks in the :version:push namespace for each configured
+  # Git remote, allowing individual pushes to specific remotes.
+  # - It also defines a top-level :version:push task that depends on all the
+  # individual remote push tasks, enabling a single command to push the version
+  # tag to all remotes.
+  #
+  # The tasks utilize the git_remotes method to determine which remotes are
+  # configured and generate appropriate push commands for each one.
   def version_push_task
     namespace :version do
       git_remotes.each do |gr|
@@ -542,6 +778,19 @@ class GemHadar
     end
   end
 
+  # The master_push_task method defines Rake tasks for pushing the master
+  # branch to configured Git remotes.
+  #
+  # This method sets up a hierarchical task structure under the :master namespace:
+  #
+  # - It creates subtasks in the :master:push namespace for each configured Git
+  #   remote, allowing individual pushes to specific remotes.
+  # - It also defines a top-level :master:push task that depends on all the individual
+  #   remote push tasks, enabling a single command to push the master branch to
+  #   all remotes.
+  #
+  # The tasks utilize the git_remotes method to determine which remotes are
+  # configured and generate appropriate push commands for each one.
   def master_push_task
     namespace :master do
       git_remotes.each do |gr|
@@ -558,6 +807,17 @@ class GemHadar
     end
   end
 
+  # The gem_push_task method defines a Rake task for pushing the generated gem
+  # file to RubyGems.
+  #
+  # This method sets up a :gem:push task under the Rake namespace that handles
+  # the process of uploading the gem package to RubyGems. It checks if the
+  # project is in developing mode and skips the push operation if so.
+  # Otherwise, it verifies the existence of the gem file, prompts the user for
+  # confirmation before pushing, and uses the gem push command with an optional
+  # API key from the environment. If the gem file does not exist or the user
+  # declines to push, appropriate messages are displayed and the task exits
+  # accordingly.
   def gem_push_task
     namespace :gem do
       path = "pkg/#{name_version}.gem"
@@ -586,6 +846,15 @@ class GemHadar
     end
   end
 
+  # The git_remotes_task method defines a Rake task that displays all Git
+  # remote repositories configured for the project.
+  #
+  # This method sets up a :git_remotes task under the Rake namespace that
+  # retrieves and prints the list of Git remotes along with their URLs. It uses
+  # the git_remotes method to obtain the remote names and then fetches each
+  # remote's URL using the `git remote get-url` command. The output is
+  # formatted to show each remote name followed by its corresponding URL on
+  # separate lines.
   def git_remotes_task
     task :git_remotes do
       puts git_remotes.map { |r|
@@ -595,65 +864,29 @@ class GemHadar
     end
   end
 
-  def create_body
-    base_url = ENV['OLLAMA_URL']
-    if base_url.blank? && host = ENV['OLLAMA_HOST'].full?
-      base_url = 'http://%s' % host
-    end
-    base_url.present? or return
+  # The create_git_release_body method generates a changelog for a GitHub
+  # release by analyzing the git diff between the previous version and the
+  # current HEAD.
+  #
+  # It retrieves the log differences, fetches or uses default system and prompt
+  # templates, and utilizes an AI model to produce a formatted changelog entry.
+  #
+  # @return [ String ] the generated changelog content for the release body
+  def create_git_release_body
     log_diff = version_log_diff(to_version: version)
-    model    = ENV.fetch('OLLAMA_MODEL', 'llama3.1')
-    ollama   = Ollama::Client.new(base_url:, read_timeout: 600, connect_timeout: 60)
-    system = <<~EOT
-      You are a Ruby programmer generating changelog messages in markdown
-      format for new releases, so users can see what has changed. Remember you
-      are not a chatbot of any kind.
-    EOT
-    prompt = (<<~EOT) % { name:, version:, log_diff: }
-      Output the content of a changelog for the new release of %{name} %{version}
-
-      **Strictly** follow these guidelines:
-
-        - Use bullet points in markdown format (`-`) to list significant changes.
-        - Exclude trivial updates such as:
-          * Version number increments
-          * Dependency version bumps (unless they resolve critical issues)
-          * Minor code style adjustments
-          * Internal documentation tweaks
-        - Include only verified and substantial changes that impact
-          functionality, performance, or user experience.
-        - If unsure about a change's significance, omit it from the output.
-        - Avoid adding any comments or notes; keep the output purely factual.
-
-      These are the log messages including patches for the new release:
-
-      %{log_diff}
-    EOT
-    options = ENV['OLLAMA_OPTIONS'].full? { |o| JSON.parse(o) } || {}
-    options |= { "temperature" => 0, "top_p" => 1, "min_p" => 0.1 }
-    ollama.generate(model:, system:, prompt:, options:, stream: false, think: false).response
-  end
-
-  def edit_temp_file(content)
-    editor = ENV.fetch('EDITOR', `which vi`.chomp)
-    unless File.exist?(editor)
-      warn "Can't find EDITOR. => Returning."
-      return
-    end
-    temp_file = Tempfile.new('changelog')
-    temp_file.write(content)
-    temp_file.close
-
-    unless system("#{editor} #{temp_file.path}")
-      warn "#{editor} returned #{$?.exitstatus} => Returning."
-      return
-    end
-
-    File.read(temp_file.path)
-  ensure
-    temp_file&.close&.unlink
+    system   = xdg_config('release_system_prompt.txt', default_git_release_system_prompt)
+    prompt   = xdg_config('release_prompt.txt', default_git_release_prompt) % { name:, version:, log_diff: }
+    ollama_generate(system:, prompt:)
   end
 
+  # The github_release_task method defines a Rake task that creates a GitHub
+  # release for the current version.
+  #
+  # This method sets up a :github:release task that prompts the user to confirm
+  # publishing a release message on GitHub. It retrieves the GitHub API token
+  # from the environment, derives the repository owner and name from the git
+  # remote URL, generates a changelog using AI, and creates the release via the
+  # GitHub API.
   def github_release_task
     namespace :github do
       unless github_api_token = ENV['GITHUB_API_TOKEN'].full?
@@ -661,7 +894,7 @@ class GemHadar
         task :release
         return
       end
-      desc "Create a new GitHub release for the current version with a changelog"
+      desc "Create a new GitHub release for the current version with a AI-generated changelog"
       task :release do
         yes = ask?(
           "Do you want to publish a release message on github? (y/n%{default}) ",
@@ -675,7 +908,7 @@ class GemHadar
           rc = GitHub::ReleaseCreator.new(owner:, repo:, token: github_api_token)
           tag_name         = version_tag(version)
           target_commitish = `git show -s --format=%H #{tag_name.inspect}^{commit}`.chomp
-          body             = edit_temp_file(create_body)
+          body             = edit_temp_file(create_git_release_body)
           if body.present?
             begin
               response = rc.perform(tag_name:, target_commitish:, body:)
@@ -695,6 +928,14 @@ class GemHadar
 
   dsl_accessor :push_task_dependencies, %i[ modified build master:push version:push gem:push github:release ]
 
+  # The push_task method defines a Rake task that orchestrates the complete
+  # process of pushing changes and artifacts to remote repositories and package
+  # managers.
+  #
+  # This method sets up multiple subtasks including preparing the master
+  # branch, pushing version tags, pushing to gem repositories, and creating
+  # GitHub releases. It also includes a check for uncommitted changes before
+  # proceeding with the push operations.
   def push_task
     master_prepare_task
     version_push_task
@@ -709,10 +950,26 @@ class GemHadar
         exit 1
       end
     end
-    desc "Push master and version #{version} all git remotes: #{git_remotes * ' '}"
+    desc "Push all changes for version #{version} into the internets."
     task :push => push_task_dependencies
   end
 
+  # The release_task method defines a Rake task that orchestrates the complete
+  # release process for the gem.
+  #
+  # This method sets up a :release task that depends on the :push task,
+  # ensuring all necessary steps for publishing the gem are executed in
+  # sequence. It provides a convenient way to perform a full release workflow
+  # with a single command.
+  def release_task
+    desc "Release the new version #{version} for the gem #{name}."
+    task :release => :push
+  end
+
+  # The compile_task method sets up a Rake task to compile project extensions.
+  #
+  # This method creates a :compile task that iterates through the configured
+  # extensions and compiles them using the system's make command.
   def compile_task
     for file in extensions
       dir = File.dirname(file)
@@ -730,6 +987,16 @@ class GemHadar
     end
   end
 
+  # The rvm_task method creates a .rvmrc file that configures RVM to use the
+  # specified Ruby version and gemset for the project.
+  #
+  # This task generates a .rvmrc file in the project root directory with commands to:
+  # - Use the Ruby version specified by the rvm.use accessor
+  # - Create the gemset specified by the rvm.gemset accessor
+  # - Switch to using that gemset
+  #
+  # The generated file is written using the secure_write method to ensure
+  # proper file permissions.
   def rvm_task
     desc 'Create .rvmrc file'
     task :rvm do
@@ -743,15 +1010,55 @@ class GemHadar
     end
   end
 
+  def yard_doc_task
+    YARD::Rake::YardocTask.new(:yard_doc) do |t|
+      t.files = files.select { _1 =~ /\.rb\z/ }
+
+      output_dir = yard_dir
+      t.options = [ "--output-dir=#{output_dir}" ]
+
+      # Include private & protected methods in documentation
+      t.options << '--private' << '--protected'
+
+      # Handle readme if present
+      if readme && File.exist?(readme)
+        t.options << "--readme=#{readme}"
+      end
+
+      # Add additional documentation files
+      if doc_files&.any?
+        t.files.concat(doc_files.flatten)
+      end
+
+      # Add before hook for cleaning
+      t.before = proc {
+        clean output_dir
+        puts "Generating full documentation in #{output_dir}..."
+      }
+    end
+  end
+
+  # The yard_task method sets up and registers Rake tasks for generating and
+  # managing YARD documentation.
+  #
+  # It creates multiple subtasks under the :yard namespace, including tasks for
+  # creating private documentation, viewing the generated documentation,
+  # cleaning up documentation files, and listing undocumented elements.
+  # If YARD is not available, the method returns early without defining any tasks.
   def yard_task
     defined? YARD or return
+    yard_doc_task
+    desc 'Create yard documentation (including private)'
+    task :doc => :yard_doc
     namespace :yard do
       my_yard_dir = Pathname.new(yard_dir)
 
-      desc 'Create yard documentation (including private)'
-      task :private do
-        sh "yardoc -o #{my_yard_dir}"
-      end
+      task :private => :yard_doc
+
+      task :public => :yard_doc
+
+      desc 'Create yard documentation'
+      task :doc => :yard_doc
 
       desc 'View the yard documentation'
       task :view do
@@ -789,7 +1096,6 @@ class GemHadar
     gem_hadar_update_task
     gemspec_task
     gems_install_task
-    doc_task
     if test_dir
       test_task
       rcov_task
@@ -801,6 +1107,7 @@ class GemHadar
     version_bump_task
     version_tag_task
     push_task
+    release_task
     write_ignore_file
     write_gemfile
     if extensions.full?
@@ -812,6 +1119,77 @@ class GemHadar
     self
   end
 
+  # The edit_temp_file method creates a temporary file with the provided
+  # content, opens it in an editor for user modification, and returns the
+  # updated content.
+  #
+  # @param content [ String ] the initial content to write to the temporary file
+  def edit_temp_file(content)
+    editor = ENV.fetch('EDITOR', `which vi`.chomp)
+    unless File.exist?(editor)
+      warn "Can't find EDITOR. => Returning."
+      return
+    end
+    temp_file = Tempfile.new('changelog')
+    temp_file.write(content)
+    temp_file.close
+
+    unless system("#{editor} #{temp_file.path}")
+      warn "#{editor} returned #{$?.exitstatus} => Returning."
+      return
+    end
+
+    File.read(temp_file.path)
+  ensure
+    temp_file&.close&.unlink
+  end
+
+  # Generates a response from an AI model using the Ollama::Client.
+  #
+  # @param [String] system The system prompt for the AI model.
+  # @param [String] prompt The user prompt to generate a response to.
+  # @return [String, nil] The generated response or nil if generation fails.
+  def ollama_generate(system:, prompt:)
+    base_url = ENV['OLLAMA_URL']
+    if base_url.blank? && host = ENV['OLLAMA_HOST'].full?
+      base_url = 'http://%s' % host
+    end
+    base_url.present? or return
+    ollama   = Ollama::Client.new(base_url:, read_timeout: 600, connect_timeout: 60)
+    model    = ENV.fetch('OLLAMA_MODEL', 'llama3.1')
+    options  = ENV['OLLAMA_OPTIONS'].full? { |o| JSON.parse(o) } || {}
+    options |= { "temperature" => 0, "top_p" => 1, "min_p" => 0.1 }
+    ollama.generate(model:, system:, prompt:, options:, stream: false, think: false).response
+  end
+
+  # Increases the specified part of the version number and writes it back to
+  # the VERSION  file.
+  #
+  # @param [Symbol, String] type The part of the version to bump (:major, :minor, or :build)
+  def version_bump_to(type)
+    type    = type.to_sym
+    version = File.read('VERSION').chomp.version
+    version.bump(type)
+    secure_write('VERSION') { |v| v.puts version }
+    exit 0
+  end
+
+  # Determine the start and end versions for diff comparison.
+  #
+  # If the VERSION env var is set, it will be used as the starting version tag.
+  # Otherwise, it defaults to the current commit's version or the latest tag.
+  #
+  # @return [Array(String, String)] A fixed-size array containing:
+  #   - The start version (e.g., '1.2.3') from which changes are compared.
+  #   - The end version (e.g., '1.2.4' or 'HEAD') up to which changes are compared.
+  def determine_version_range
+    version_tags = versions.map { version_tag(_1) } + %w[ HEAD ]
+    found_version_tag = version_tags.index(version_tag(version))
+    found_version_tag.nil? and fail "cannot find version tag #{version_tag(version)}"
+    start_version, end_version = version_tags[found_version_tag, 2]
+    return start_version, end_version
+  end
+
   # The write_ignore_file method writes the current ignore_files configuration
   # to a .gitignore file in the project root directory.
   def write_ignore_file
@@ -909,8 +1287,12 @@ class GemHadar
         s.rdoc_options << '--title' << "#{name.camelize} - #{summary}"
       end
       if readme
-        s.rdoc_options << '--main' << readme
-        s.extra_rdoc_files << readme
+        if File.exist?(readme)
+          s.rdoc_options << '--main' << readme
+          s.extra_rdoc_files << readme
+        else
+          warn "Add a #{readme} file to document your gem!"
+        end
       end
       doc_files.full? { |df| s.extra_rdoc_files.concat Array(df) }
     end
@@ -934,12 +1316,6 @@ class GemHadar
     end
     super(*args)
   end
-  def fail(*args)
-    args.map! do |a|
-      a.respond_to?(:to_str) ? color(196) { a.to_str } : a
-    end
-    super(*args)
-  end
 
   # The git_remotes method retrieves the list of remote repositories configured
   # for the current Git project.
@@ -999,19 +1375,33 @@ class GemHadar
   #
   # @return [ Array<String> ] an array of version strings sorted in ascending
   # order according to semantic versioning rules.
+  memoize method:
   def versions
-    @versions ||= `git tag`.lines.grep(/^v?\d+\.\d+\.\d+$/).map(&:chomp).map {
+    `git tag`.lines.grep(/^v?\d+\.\d+\.\d+$/).map(&:chomp).map {
       _1.sub(/\Av/, '')
     }.sort_by(&:version)
   end
 
   # The version_tag method prepends a 'v' prefix to the given version
-  # string.
+  # string, unless it's HEAD.
   #
   # @param version [String] the version string to modify
   # @return [String] the modified version string with a 'v' prefix
   def version_tag(version)
-    version.dup.prepend ?v
+    if version != 'HEAD'
+      version.dup.prepend ?v
+    else
+      version.dup
+    end
+  end
+
+  # The version_untag method removes the 'v' prefix from a version tag string.
+  #
+  # @param version_tag [ String ] the version tag string that may start with 'v'
+  #
+  # @return [ String ] the version string with the 'v' prefix removed
+  def version_untag(version_tag)
+    version.sub(/\Av/, '')
   end
 
   # The github_remote_url method retrieves and parses the GitHub remote URL