kettle-dev 1.0.9 → 1.0.11

data/exe/kettle-changelog

@@ -0,0 +1,401 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# vim: set syntax=ruby
+
+# kettle-changelog: Generate a CHANGELOG.md entry for the current VERSION.
+# - Reads VERSION from lib/**/version.rb (must be unique across files)
+# - Moves entries from the "Unreleased" section into a new versioned section
+# - Prepends 4 heading lines:
+#   - TAG
+#   - COVERAGE (line coverage)
+#   - BRANCH COVERAGE (branch coverage)
+#   - percent documented (parsed from `bin/yard` output)
+# - Updates bottom link references to GitHub style, converts any existing
+#   GitLab links to GitHub links, and appends the new [X.Y.Z] and [X.Y.Zt] links.
+#
+# Notes:
+# - Expects a JSON coverage report at coverage/coverage.json. If missing,
+#   it will instruct you to run: K_SOUP_COV_FORMATTERS="json" bin/rspec
+# - Expects bin/yard to be available via Bundler.
+
+$stdout.sync = true
+
+# Depending library or project must be using bundler
+require "bundler/setup"
+
+require "json"
+require "time"
+require "open3"
+require "shellwords"
+
+begin
+  require "kettle/dev"
+rescue LoadError => e
+  warn("kettle/dev: failed to load: #{e.message}")
+  warn("Hint: Ensure the host project includes kettle-dev and run bundle install.")
+  exit(1)
+end
+
+require "kettle/dev/versioning"
+
+puts "== kettle-changelog v#{Kettle::Dev::Version::VERSION} =="
+
+module Kettle
+  module Dev
+    class ChangelogCLI
+      def initialize
+        @root = Kettle::Dev::CIHelpers.project_root
+        @changelog_path = File.join(@root, "CHANGELOG.md")
+        @coverage_path = File.join(@root, "coverage", "coverage.json")
+      end
+
+      def run
+        version = Kettle::Dev::Versioning.detect_version(@root)
+        today = Time.now.strftime("%Y-%m-%d")
+        owner, repo = Kettle::Dev::CIHelpers.repo_info
+        unless owner && repo
+          warn("Could not determine GitHub owner/repo from origin remote.")
+          warn("Make sure 'origin' points to github.com. Alternatively, set origin or update links manually afterward.")
+        end
+
+        line_cov_line, branch_cov_line = coverage_lines
+        yard_line = yard_percent_documented
+
+        changelog = File.read(@changelog_path)
+
+        # If the detected version already exists in the changelog, abort to avoid duplicates
+        if changelog =~ /^## \[#{Regexp.escape(version)}\]/
+          abort("CHANGELOG.md already has a section for version #{version}. Bump version.rb or remove the duplicate.")
+        end
+
+        unreleased_block, before, after = extract_unreleased(changelog)
+        if unreleased_block.nil?
+          abort("Could not find '## [Unreleased]' section in CHANGELOG.md")
+        end
+
+        if unreleased_block.strip.empty?
+          warn("No entries found under Unreleased. Creating an empty version section anyway.")
+        end
+
+        prev_version = detect_previous_version(after)
+
+        new_section = +""
+        new_section << "## [#{version}] - #{today}\n"
+        new_section << "- TAG: [v#{version}][#{version}t]\n"
+        new_section << "- #{line_cov_line}\n" if line_cov_line
+        new_section << "- #{branch_cov_line}\n" if branch_cov_line
+        new_section << "- #{yard_line}\n" if yard_line
+        new_section << filter_unreleased_sections(unreleased_block)
+        # Ensure exactly one blank line separates this new section from the next section
+        new_section.rstrip!
+        new_section << "\n\n"
+
+        # Reset the Unreleased section to empty category headings
+        unreleased_reset = <<~MD
+          ## [Unreleased]
+          ### Added
+          ### Changed
+          ### Deprecated
+          ### Removed
+          ### Fixed
+          ### Security
+        MD
+
+        updated = before + unreleased_reset + "\n" + new_section + after
+
+        updated = update_link_refs(updated, owner, repo, prev_version, version)
+
+        File.write(@changelog_path, updated)
+        puts "CHANGELOG.md updated with v#{version} section."
+      end
+
+      private
+
+      def abort(msg)
+        Kettle::Dev::ExitAdapter.abort(msg)
+      rescue NameError
+        Kernel.abort(msg)
+      end
+
+      def detect_version
+        candidates = Dir[File.join(@root, "lib", "**", "version.rb")]
+        abort("Could not find version.rb under lib/**.") if candidates.empty?
+        versions = candidates.map do |path|
+          content = File.read(path)
+          m = content.match(/VERSION\s*=\s*(["'])([^"']+)\1/)
+          next unless m
+          m[2]
+        end.compact
+        abort("VERSION constant not found in #{@root}/lib/**/version.rb") if versions.none?
+        abort("Multiple VERSION constants found to be out of sync (#{versions.inspect}) in #{@root}/lib/**/version.rb") unless versions.uniq.length == 1
+        versions.first
+      end
+
+      def extract_unreleased(content)
+        lines = content.lines
+        start_i = lines.index { |l| l.start_with?("## [Unreleased]") }
+        return [nil, nil, nil] unless start_i
+        # Find the next version heading after Unreleased
+        next_i = (start_i + 1)
+        while next_i < lines.length && !lines[next_i].start_with?("## [")
+          next_i += 1
+        end
+        # Now next_i points to the next section heading or EOF
+        before = lines[0..(start_i - 1)].join
+        unreleased_block = lines[(start_i + 1)..(next_i - 1)].join
+        after = lines[next_i..-1]&.join || ""
+        [unreleased_block, before, after]
+      end
+
+      def detect_previous_version(after_text)
+        # after_text begins with the first released section following Unreleased
+        m = after_text.match(/^## \[(\d+\.\d+\.\d+)\]/)
+        return m[1] if m
+        nil
+      end
+
+      # From the Unreleased block, keep only sections that have content.
+      # We detect sections as lines starting with '### '. A section has content if there is at least
+      # one non-empty, non-heading line under it before the next '###' or '##'. Typically these are list items.
+      # Returns a string that includes only the non-empty sections with their content.
+      def filter_unreleased_sections(unreleased_block)
+        lines = unreleased_block.lines
+        out = []
+        i = 0
+        while i < lines.length
+          line = lines[i]
+          if line.start_with?("### ")
+            header = line
+            i += 1
+            chunk = []
+            while i < lines.length && !lines[i].start_with?("### ") && !lines[i].start_with?("## ")
+              chunk << lines[i]
+              i += 1
+            end
+            # Determine if chunk has any content (non-blank)
+            content_present = chunk.any? { |l| l.strip != "" }
+            if content_present
+              # Trim trailing blank lines
+              while chunk.any? && chunk.last.strip == ""
+                chunk.pop
+              end
+              out << header
+              out.concat(chunk)
+              out << "\n" unless out.last&.end_with?("\n")
+            end
+            next
+          else
+            # Lines outside sections are ignored for released sections
+            i += 1
+          end
+        end
+        out.join
+      end
+
+      def coverage_lines
+        unless File.file?(@coverage_path)
+          warn("Coverage JSON not found at #{@coverage_path}.")
+          warn("Run: K_SOUP_COV_FORMATTERS=\"json\" bin/rspec")
+          return [nil, nil]
+        end
+        data = JSON.parse(File.read(@coverage_path))
+        files = data["coverage"] || {}
+        file_count = 0
+        total_lines = 0
+        covered_lines = 0
+        total_branches = 0
+        covered_branches = 0
+        files.each_value do |h|
+          lines = h["lines"] || []
+          line_relevant = lines.count { |x| x.is_a?(Integer) }
+          line_covered = lines.count { |x| x.is_a?(Integer) && x > 0 }
+          if line_relevant > 0
+            file_count += 1
+            total_lines += line_relevant
+            covered_lines += line_covered
+          end
+          branches = h["branches"] || []
+          branches.each do |b|
+            next unless b.is_a?(Hash)
+            cov = b["coverage"]
+            next unless cov.is_a?(Numeric)
+            total_branches += 1
+            covered_branches += 1 if cov > 0
+          end
+        end
+        line_pct = (total_lines > 0) ? ((covered_lines.to_f / total_lines) * 100.0) : 0.0
+        branch_pct = (total_branches > 0) ? ((covered_branches.to_f / total_branches) * 100.0) : 0.0
+        line_str = format("COVERAGE: %.2f%% -- %d/%d lines in %d files", line_pct, covered_lines, total_lines, file_count)
+        branch_str = format("BRANCH COVERAGE: %.2f%% -- %d/%d branches in %d files", branch_pct, covered_branches, total_branches, file_count)
+        [line_str, branch_str]
+      rescue StandardError => e
+        warn("Failed to parse coverage: #{e.class}: #{e.message}")
+        [nil, nil]
+      end
+
+      def yard_percent_documented
+        cmd = File.join(@root, "bin", "yard")
+        unless File.executable?(cmd)
+          warn("bin/yard not found or not executable; ensure yard is installed via bundler")
+          return
+        end
+        out, _ = Open3.capture2(cmd)
+        # Look for a line containing e.g., "95.35% documented"
+        line = out.lines.find { |l| l =~ /\d+(?:\.\d+)?%\s+documented/ }
+        if line
+          line = line.strip
+          # Return exactly as requested: e.g. "95.35% documented"
+          line
+        else
+          warn("Could not find documented percentage in bin/yard output.")
+          nil
+        end
+      rescue StandardError => e
+        warn("Failed to run bin/yard: #{e.class}: #{e.message}")
+        nil
+      end
+
+      def update_link_refs(content, owner, repo, prev_version, new_version)
+        # Convert any GitLab links to GitHub
+        content = content.gsub(%r{https://gitlab\.com/([^/]+)/([^/]+)/-/compare/([^\.]+)\.\.\.([^\s]+)}) do
+          o = owner || Regexp.last_match(1)
+          r = repo || Regexp.last_match(2)
+          from = Regexp.last_match(3)
+          to = Regexp.last_match(4)
+          "https://github.com/#{o}/#{r}/compare/#{from}...#{to}"
+        end
+        content = content.gsub(%r{https://gitlab\.com/([^/]+)/([^/]+)/-/tags/(v[^\s\]]+)}) do
+          o = owner || Regexp.last_match(1)
+          r = repo || Regexp.last_match(2)
+          tag = Regexp.last_match(3)
+          "https://github.com/#{o}/#{r}/releases/tag/#{tag}"
+        end
+
+        # Append or update the bottom reference links
+        lines = content.lines
+
+        # Find the index of the Unreleased heading; only manipulate refs after this point
+        unreleased_idx = lines.index { |l| l.start_with?("## [Unreleased]") } || -1
+
+        # Find the first link-ref line (e.g., "[Unreleased]: http...") AFTER Unreleased
+        first_ref = nil
+        lines.each_with_index do |l, i|
+          if l =~ /^\[[^\]]+\]:\s+http/ && i > unreleased_idx
+            first_ref = i
+            break
+          end
+        end
+        unless first_ref
+          # Append at end if no ref block after Unreleased
+          first_ref = lines.length
+          lines << "\n"
+        end
+
+        # Ensure Unreleased points to GitHub compare from new tag to HEAD
+        if owner && repo
+          unreleased_ref = "[Unreleased]: https://github.com/#{owner}/#{repo}/compare/v#{new_version}...HEAD\n"
+          # Update an existing Unreleased ref only if it appears after Unreleased heading; otherwise append
+          idx = nil
+          lines.each_with_index do |l, i|
+            if l.start_with?("[Unreleased]:") && i >= first_ref
+              idx = i
+              break
+            end
+          end
+          if idx
+            lines[idx] = unreleased_ref
+          else
+            lines << unreleased_ref
+          end
+        end
+
+        if owner && repo
+          # Add compare link for the new version
+          from = prev_version ? "v#{prev_version}" : detect_initial_compare_base(lines)
+          new_compare = "[#{new_version}]: https://github.com/#{owner}/#{repo}/compare/#{from}...v#{new_version}\n"
+          unless lines.any? { |l| l.start_with?("[#{new_version}]:") }
+            lines << new_compare
+          end
+          # Add tag link for the new version
+          new_tag = "[#{new_version}t]: https://github.com/#{owner}/#{repo}/releases/tag/v#{new_version}\n"
+          unless lines.any? { |l| l.start_with?("[#{new_version}t]:") }
+            lines << new_tag
+          end
+        end
+
+        # Rebuild and sort the reference block so newest is at the bottom, preserving everything above first_ref
+        ref_lines = lines[first_ref..-1].select { |l| l =~ /^\[[^\]]+\]:\s+http/ }
+        # Deduplicate by key (text inside the square brackets)
+        by_key = {}
+        ref_lines.each do |l|
+          if l =~ /^\[([^\]]+)\]:\s+/
+            by_key[$1] = l
+          end
+        end
+        unreleased_line = by_key.delete("Unreleased")
+        # Separate version compare and tag links
+        compares = {}
+        tags = {}
+        by_key.each do |k, v|
+          if k =~ /^(\d+\.\d+\.\d+)$/
+            compares[$1] = v
+          elsif k =~ /^(\d+\.\d+\.\d+)t$/
+            tags[$1] = v
+          end
+        end
+        # Sort versions ascending so newest at bottom
+        sorted_versions = compares.keys.map { |s| Gem::Version.new(s) }.sort.map(&:to_s)
+        # In case some versions only have tags or only compares, include them as well
+        (tags.keys - compares.keys).each { |s| sorted_versions |= [s] }
+        sorted_versions = sorted_versions.map { |s| Gem::Version.new(s) }.sort.map(&:to_s)
+
+        new_ref_block = []
+        new_ref_block << unreleased_line if unreleased_line
+        sorted_versions.each do |v|
+          new_ref_block << compares[v] if compares[v]
+          new_ref_block << tags[v] if tags[v]
+        end
+        # Replace the old block
+        rebuilt = lines[0...first_ref] + new_ref_block + ["\n"]
+        rebuilt.join
+      end
+
+      def detect_initial_compare_base(lines)
+        # Fallback when prev_version is unknown: try to find the first compare base used historically
+        # e.g., for 1.0.0 it may be a commit SHA instead of a tag
+        ref = lines.find { |l| l =~ /^\[1\.0\.0\]:\s+https:\/\/github\.com\// }
+        if ref && (m = ref.match(%r{compare/([^\.]+)\.\.\.v\d+})).is_a?(MatchData)
+          m[1]
+        else
+          # Default to previous tag name if none found (unlikely to be correct, but better than empty)
+          "HEAD^"
+        end
+      end
+    end
+  end
+end
+
+begin
+  if ARGV.include?("-h") || ARGV.include?("--help")
+    puts <<~USAGE
+      Usage: kettle-changelog
+
+      Generates a new CHANGELOG.md entry for the current version detected from lib/**/version.rb.
+      Moves entries from [Unreleased] into the new section, adds coverage and documentation stats,
+      and updates bottom link references to GitHub style, adding new compare/tag links.
+
+      Prerequisites:
+        - coverage/coverage.json present (run: K_SOUP_COV_FORMATTERS="json" bin/rspec)
+        - yard installed and available via bin/yard
+    USAGE
+    exit(0)
+  end
+  Kettle::Dev::ChangelogCLI.new.run
+rescue SystemExit
+  raise
+rescue StandardError => e
+  warn("kettle-changelog: unexpected error: #{e.class}: #{e.message}")
+  warn(e.backtrace.join("\n")) if ENV["DEBUG"]
+  exit(1)
+end

data/exe/kettle-commit-msg

@@ -1,16 +1,20 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
+
 # vim: set syntax=ruby
 
-require "rubygems"
-begin
-  require "bundler/setup"
-rescue LoadError
-  # Allow running outside of Bundler; runtime deps should still be available via rubygems
-end
+# Immediate, unbuffered output
+$stdout.sync = true
+# Depending library or project must be using bundler
+require "bundler/setup"
 
 # Standard library
 require "erb"
 
+require "kettle/dev"
+
+puts "== kettle-commit-msg v#{Kettle::Dev::Version::VERSION} =="
+
 # ENV variable control (set in .envrc, or .env.local)
 # BRANCH_RULE_TYPE = jira, or another type of branch rule validation, or false to disable
 # FOOTER_APPEND = true/false append commit message footer
@@ -48,140 +52,4 @@ else
   # puts "No branch rule configured (set GIT_HOOK_BRANCH_VALIDATE=jira to enforce rules for jira style branch names)"
 end
 
-class GitCommitFooter
-  # Prefer project-local .git-hooks (repo root), then fallback to global ~/.git-hooks
-  NAME_ASSIGNMENT_REGEX = /\bname\s*=\s*(["'])([^"']+)\1/.freeze
-  FOOTER_APPEND = ENV.fetch("GIT_HOOK_FOOTER_APPEND", "false").casecmp("true").zero?
-  SENTINEL = ENV["GIT_HOOK_FOOTER_SENTINEL"] # No default to avoid accidental duplicate commit of a footer via ammended commits
-  raise "Set GIT_HOOK_FOOTER_SENTINEL=<footer sentinel> in .env.local (e.g., '⚡️ A message from a fellow meat-based-AI ⚡️')" if FOOTER_APPEND && (SENTINEL.nil? || SENTINEL.to_s.empty?)
-
-  class << self
-    def git_toplevel
-      toplevel = nil
-      begin
-        # 'git rev-parse --show-toplevel' returns the repo root when run anywhere inside the repo
-        out = %x(git rev-parse --show-toplevel 2>/dev/null)
-        toplevel = out.strip unless out.nil? || out.empty?
-      rescue StandardError
-        # ignore
-      end
-      toplevel
-    end
-
-    def local_hooks_dir
-      top = git_toplevel
-      return unless top && !top.empty?
-      File.join(top, ".git-hooks")
-    end
-
-    def global_hooks_dir
-      File.join(ENV["HOME"], ".git-hooks")
-    end
-
-    def hooks_path_for(filename)
-      local_dir = local_hooks_dir
-      if local_dir
-        local_path = File.join(local_dir, filename)
-        return local_path if File.file?(local_path)
-      end
-      File.join(global_hooks_dir, filename)
-    end
-
-    def commit_goalie_path
-      hooks_path_for("commit-subjects-goalie.txt")
-    end
-
-    # Determine whether the commit subject allows footer append, based on optional goalie file
-    # ~/.git-hooks/commit-subjects-goalie.txt
-    # - If present, only allow appending when the first line of the commit message starts with one of the non-commented prefixes
-    # - If absent, disallow footer
-    def goalie_allows_footer?(subject_line)
-      goalie_path = commit_goalie_path
-      return false unless File.file?(goalie_path)
-
-      prefixes = File.read(goalie_path).lines.map { |l| l.strip }.reject { |l| l.empty? || l.start_with?("#") }
-      # If the file exists but has no usable lines, treat as deny-all per goalie intent
-      return false if prefixes.empty?
-
-      subj = subject_line.to_s.strip
-      prefixes.any? { |prefix| subj.start_with?(prefix) }
-    end
-
-    def render(*argv)
-      commit_msg = File.read(argv[0])
-      subject_line = commit_msg.lines.first.to_s
-      if GitCommitFooter::FOOTER_APPEND && goalie_allows_footer?(subject_line)
-        if commit_msg.include?(GitCommitFooter::SENTINEL)
-          # This is a commit message that has already been appended
-          # This will happen if the commit message is edited and re-committed
-          # puts "FOOTER_APPEND is true, skipping footer append"
-          exit(0)
-        else
-          footer_binding = GitCommitFooter.new
-          # Append footer to the commit message
-          File.open(argv[0], "w") do |file|
-            file.print(commit_msg)
-            file.print("\n")
-            file.print(footer_binding.render)
-          end
-        end
-      else
-        # Skipping footer append (either FOOTER_APPEND is false, or goalie did not allow it)
-      end
-    end
-  end
-
-  def initialize
-    @pwd = Dir.pwd
-    @gemspecs = Dir["*.gemspec"]
-    @spec = @gemspecs.first
-    @gemspec_path = File.expand_path(@spec, @pwd)
-    @gem_name = parse_gemspec_name || derive_gem_name
-  end
-
-  # Render ERB with binding variables
-  def render
-    ERB.new(template).result(binding)
-  end
-
-  private
-
-  # Lightweight parse for gem name to avoid full Gem::Specification load
-  def parse_gemspec_name
-    begin
-      content = File.read(@gemspec_path)
-      # Look for name assignment patterns like:
-      #   spec.name = "my_gem" OR Gem::Specification.new do |spec|; spec.name = 'my_gem'
-      @name_index = content =~ NAME_ASSIGNMENT_REGEX
-      if @name_index
-        return $2
-      end
-    rescue StandardError
-      # fall through
-    end
-    nil
-  end
-
-  # No-parse derivation of gem name, when parsing gemspec fails
-  def derive_gem_name
-    File.basename(@gemspec_path, ".*") if @gemspec_path
-  end
-
-  # Example
-  #
-  #     ⚡️ A message from a fellow meat-based-AI ⚡️
-  #     I ❤️ working on <%= @gem_name %>.
-  #
-  # The first line is the footer sentinel (which does appear in the commit).
-  # The second line, and any additional, is the main body of the footer.
-  #
-  # The sentinel must be set in an ENV variable (e.g., in your .env.local file):
-  #
-  #   export GIT_HOOK_FOOTER_SENTINEL="⚡️ A message from a fellow meat-based-AI ⚡️"
-  #
-  def template
-    File.read(self.class.hooks_path_for("footer-template.erb.txt"))
-  end
-end
-
-GitCommitFooter.render(*ARGV)
+Kettle::Dev::GitCommitFooter.render(*ARGV)