kettle-dev 2.0.0 → 2.0.1

data/lib/kettle/dev/gem_spec_reader.rb

@@ -6,11 +6,15 @@ module Kettle
   module Dev
     # Unified gemspec reader using RubyGems loader instead of regex parsing.
     # Returns a Hash with all data used by this project from gemspecs.
-    # Cache within the process to avoid repeated loads.
+    # Results are memoized per project root within the process.
     class GemSpecReader
       # Default minimum Ruby version to assume when a gemspec doesn't specify one.
       # @return [Gem::Version]
       DEFAULT_MINIMUM_RUBY = Gem::Version.new("1.8").freeze
+      CacheState = Struct.new(:entries, :mutex)
+      CACHE = CacheState.new({}, Mutex.new)
+      private_constant :CacheState, :CACHE
+
       class << self
         # Load gemspec data for the project at root using RubyGems.
         # The reader is lenient: failures to load or missing fields are handled with defaults and warnings.
@@ -39,6 +43,11 @@ module Kettle
         # @option return [String] :bindir
         # @option return [Array<String>] :executables
         def load(root)
+          cache_key = File.expand_path(root.to_s)
+          CACHE.mutex.synchronize do
+            return CACHE.entries[cache_key] if CACHE.entries.key?(cache_key)
+          end
+
           gemspec_path = Dir.glob(File.join(root.to_s, "*.gemspec")).first
           spec = nil
           if gemspec_path && File.file?(gemspec_path)
@@ -50,10 +59,21 @@ module Kettle
             end
           end
 
+          gemspec_source = if gemspec_path && File.file?(gemspec_path)
+            begin
+              File.read(gemspec_path)
+            rescue StandardError => e
+              Kettle::Dev.debug_error(e, __method__)
+              ""
+            end
+          else
+            ""
+          end
+
           gem_name = spec&.name.to_s
           if gem_name.nil? || gem_name.strip.empty?
             # Be lenient here for tasks that can proceed without gem_name (e.g., choosing destination filenames).
-            Kernel.warn("kettle-dev: Could not derive gem name. Ensure a valid <name> is set in the gemspec.\n  - Tip: set the gem name in your .gemspec file (spec.name).\n  - Path searched: #{gemspec_path || "(none found)"}")
+            Kernel.warn("kettle-dev: Could not derive gem name. Ensure a valid <name> is set in the gemspec.\n  - Tip: set the gem name in your .gemspec file (spec.name).\n  - Path searched: #{Kettle::Dev.display_path(gemspec_path || "(none found)")}")
             gem_name = ""
           end
           # minimum ruby version: derived from spec.required_ruby_version
@@ -80,9 +100,11 @@ module Kettle
 
           homepage_val = spec&.homepage.to_s
 
+          explicit_forge_org = env_org_override("FORGE_ORG")
+
           # Derive org/repo from homepage or git remote
           forge_info = derive_forge_and_origin_repo(homepage_val)
-          forge_org = forge_info[:forge_org]
+          forge_org = explicit_forge_org || forge_info[:forge_org]
           gh_repo = forge_info[:origin_repo]
           if forge_org.to_s.empty?
             Kernel.warn("kettle-dev: Could not determine forge org from spec.homepage or git remote.\n  - Ensure gemspec.homepage is set to a GitHub URL or that the git remote 'origin' points to GitHub.\n  - Example homepage: https://github.com/<org>/<repo>\n  - Proceeding with default org: kettle-rb.")
@@ -92,9 +114,14 @@ module Kettle
           camel = lambda do |s|
             s.to_s.split(/[_-]/).map { |p| p.gsub(/\b([a-z])/) { Regexp.last_match(1).upcase } }.join
           end
-          namespace = gem_name.to_s.split("-").map { |seg| camel.call(seg) }.join("::")
+          entrypoint_require = derive_entrypoint_require(
+            root: root,
+            gem_name: gem_name,
+            gemspec_source: gemspec_source,
+          )
+          namespace_source = entrypoint_require.to_s.empty? ? gem_name.to_s.tr("-", "/") : entrypoint_require.to_s
+          namespace = namespace_source.split("/").reject(&:empty?).map { |seg| camel.call(seg) }.join("::")
           namespace_shield = namespace.gsub("::", "%3A%3A")
-          entrypoint_require = gem_name.to_s.tr("-", "/")
           gem_shield = gem_name.to_s.gsub("-", "--").gsub("_", "__")
 
           # Funding org (Open Collective handle) detection.
@@ -109,8 +136,9 @@ module Kettle
               funding_org = nil
             else
               env_funding = ENV["FUNDING_ORG"]
-              if env_funding && !env_funding.to_s.strip.empty?
-                # FUNDING_ORG is set and non-empty; use it as-is (already filtered by opencollective_disabled?)
+              if env_funding && !env_funding.to_s.strip.empty? && !env_funding.match?(/\{KJ\|[^}]+}/)
+                # FUNDING_ORG is set, non-empty, and is not an unresolved token placeholder;
+                # use it as-is (already filtered by opencollective_disabled?)
                 funding_org = env_funding.to_s
               else
                 # Preflight: if a YAML exists under the provided root, attempt to read it here so
@@ -131,9 +159,10 @@ module Kettle
             raise Kettle::Dev::Error, "Unable to determine funding org: #{error.message}"
           end
 
-          {
+          result = {
             gemspec_path: gemspec_path,
             gem_name: gem_name,
+            version: spec&.version.to_s,
             min_ruby: min_ruby, # Gem::Version instance
             homepage: homepage_val.to_s,
             gh_org: forge_org, # Might allow divergence from forge_org someday
@@ -155,6 +184,15 @@ module Kettle
             bindir: (spec&.bindir || "").to_s,
             executables: Array(spec&.executables),
           }
+
+          CACHE.mutex.synchronize do
+            CACHE.entries[cache_key] = result
+          end
+          result
+        end
+
+        def clear_cache!
+          CACHE.mutex.synchronize { CACHE.entries.clear }
         end
 
         private
@@ -193,6 +231,58 @@ module Kettle
 
           forge_info
         end
+
+        def env_org_override(env_key)
+          value = ENV[env_key].to_s.strip
+          return if value.empty?
+          return if value.match?(Kettle::Dev::ENV_FALSE_RE)
+          return if value.match?(/\{KJ\|[^}]+}/)
+
+          value
+        end
+
+        def derive_entrypoint_require(root:, gem_name:, gemspec_source:)
+          from_source = extract_entrypoint_require_from_gemspec_source(gemspec_source)
+          return from_source unless from_source.to_s.empty?
+
+          default_entrypoint = gem_name.to_s.tr("-", "/")
+          return default_entrypoint if default_entrypoint_path_exists?(root, default_entrypoint)
+
+          unique_version_entrypoint(root) || default_entrypoint
+        end
+
+        def extract_entrypoint_require_from_gemspec_source(source)
+          content = source.to_s
+          patterns = [
+            %r{require_relative\s+["']lib/([^"']+)/version["']},
+            %r{Kernel\.load\(\s*["'][#][{]__dir__[}]/lib/([^"']+)/version\.rb["']},
+          ]
+
+          patterns.each do |pattern|
+            match = content.match(pattern)
+            return match[1] if match && !match[1].to_s.strip.empty?
+          end
+
+          nil
+        end
+
+        def default_entrypoint_path_exists?(root, entrypoint_require)
+          return false if entrypoint_require.to_s.strip.empty?
+
+          main_file = File.join(root.to_s, "lib", "#{entrypoint_require}.rb")
+          version_file = File.join(root.to_s, "lib", entrypoint_require, "version.rb")
+          File.file?(main_file) || File.file?(version_file)
+        end
+
+        def unique_version_entrypoint(root)
+          lib_root = File.join(root.to_s, "lib")
+          return unless Dir.exist?(lib_root)
+
+          version_files = Dir.glob(File.join(lib_root, "**", "version.rb")).reject { |path| path.include?("/vendor/") }
+          return unless version_files.size == 1
+
+          version_files.first.sub(%r{\A#{Regexp.escape(lib_root)}/?}, "").sub(%r{/version\.rb\z}, "")
+        end
       end
     end
   end

data/lib/kettle/dev/git_adapter.rb

@@ -67,7 +67,7 @@ module Kettle
             @git = ::Git.open(Dir.pwd)
           end
         rescue LoadError => e
-          Kettle::Dev.debug_error(e, __method__)
+          Kettle::Dev.debug_error(e, __method__, backtrace: false)
           # Optional dependency: fall back to CLI
           @backend = :cli
         rescue StandardError => e
@@ -147,6 +147,42 @@ module Kettle
         nil
       end
 
+      # Return the list of files currently tracked by git.
+      #
+      # @return [Array<String>] relative paths of tracked files, empty on error
+      def ls_files
+        if @backend == :gem
+          begin
+            @git.ls_files.keys
+          rescue StandardError => e
+            Kettle::Dev.debug_error(e, __method__)
+            []
+          end
+        else
+          out, status = Open3.capture2("git", "ls-files")
+          status.success? ? out.split(/\r?\n/).reject(&:empty?) : []
+        end
+      rescue StandardError => e
+        Kettle::Dev.debug_error(e, __method__)
+        []
+      end
+
+      # Return the raw `git blame --porcelain` output for a single tracked file.
+      #
+      # Both backends shell out directly because the `git` gem does not provide
+      # a stable porcelain-blame interface. Callers that need only the output
+      # string (e.g. +CopyrightCollector+) should stub this method in specs.
+      #
+      # @param path [String] path to the file, relative to the repository root
+      # @return [String] raw porcelain blame output, or "" on error / untracked file
+      def blame_porcelain(path)
+        out, status = Open3.capture2("git", "blame", "--porcelain", path.to_s)
+        status.success? ? out : ""
+      rescue StandardError => e
+        Kettle::Dev.debug_error(e, __method__)
+        ""
+      end
+
       # @return [Array<String>] list of remote names
       def remotes
         if @backend == :gem

data/lib/kettle/dev/open_collective_config.rb

@@ -40,21 +40,21 @@ module Kettle
       # @return [String, nil] the handle, or nil when not required and not discoverable
       def handle(required: false, root: nil, strict: false)
         env = ENV["OPENCOLLECTIVE_HANDLE"]
-        return env unless env.nil? || env.to_s.strip.empty?
+        return env unless env.nil? || env.to_s.strip.empty? || env.match?(/\{KJ\|[^}]+}/)
 
         ypath = yaml_path(root)
         if strict
           yml = YAML.safe_load(File.read(ypath))
           if yml.is_a?(Hash)
             handle = yml["collective"] || yml[:collective] || yml["org"] || yml[:org]
-            return handle.to_s unless handle.nil? || handle.to_s.strip.empty?
+            return handle.to_s unless handle.nil? || handle.to_s.strip.empty? || handle.to_s.match?(/\{KJ\|[^}]+}/)
           end
         elsif File.file?(ypath)
           begin
             yml = YAML.safe_load(File.read(ypath))
             if yml.is_a?(Hash)
               handle = yml["collective"] || yml[:collective] || yml["org"] || yml[:org]
-              return handle.to_s unless handle.nil? || handle.to_s.strip.empty?
+              return handle.to_s unless handle.nil? || handle.to_s.strip.empty? || handle.to_s.match?(/\{KJ\|[^}]+}/)
             end
           rescue StandardError => e
             Kettle::Dev.debug_error(e, __method__) if Kettle::Dev.respond_to?(:debug_error)

data/lib/kettle/dev/pre_release_cli.rb

@@ -133,7 +133,7 @@ module Kettle
             begin
               extract_image_urls_from_text(File.read(f))
             rescue StandardError => e
-              warn("[kettle-pre-release] Could not read #{f}: #{e.class}: #{e.message}")
+              warn("[kettle-pre-release] Could not read #{Kettle::Dev.display_path(f)}: #{e.class}: #{e.message}")
               []
             end
           end
@@ -179,7 +179,7 @@ module Kettle
           begin
             original = File.read(file)
           rescue StandardError => e
-            warn("[kettle-pre-release] Could not read #{file}: #{e.class}: #{e.message}")
+            warn("[kettle-pre-release] Could not read #{Kettle::Dev.display_path(file)}: #{e.class}: #{e.message}")
             next
           end
 
@@ -199,7 +199,7 @@ module Kettle
             # Replace exact occurrences of the URL in the markdown content
             updated.gsub!(url_str, normalized)
             modified = true
-            puts "  -> #{file}: normalized #{url_str} -> #{normalized}"
+            puts "  -> #{Kettle::Dev.display_path(file)}: normalized #{url_str} -> #{normalized}"
           end
 
           if modified && updated != original
@@ -207,7 +207,7 @@ module Kettle
               File.write(file, updated)
               changed << file
             rescue StandardError => e
-              warn("[kettle-pre-release] Could not write #{file}: #{e.class}: #{e.message}")
+              warn("[kettle-pre-release] Could not write #{Kettle::Dev.display_path(file)}: #{e.class}: #{e.message}")
             end
           end
         end

data/lib/kettle/dev/rakelib/reek.rake

@@ -12,18 +12,21 @@ begin
 
   # Store current Reek output into REEK file
   require "open3"
+  require "rbconfig"
   desc("Run reek and store the output into the REEK file")
   task("reek:update") do
-    # Run via Bundler if available to ensure the right gem version is used
-    cmd = %w[bundle exec reek]
+    # Resolve the gem executable directly. `bundle exec reek` may prefer a
+    # project-local bin/reek binstub, and stale binstubs are a common failure
+    # mode during template/bootstrap work.
+    cmd = [RbConfig.ruby, Gem.bin_path("reek", "reek")]
 
     output, status = Open3.capture2e(*cmd)
 
-    File.write("REEK", output)
+    normalized_output = output.to_s.strip.empty? ? "" : output
+    File.write("REEK", normalized_output)
 
-    # Mirror the failure semantics of the standard reek task
-    unless status.success?
-      abort("reek:update failed (reek reported smells). Output written to REEK")
+    unless status.success? || status.exitstatus == 1
+      raise("reek:update failed (reek executable failed with exit #{status.exitstatus}). Output written to REEK")
     end
   end
   Kettle::Dev.register_default("reek:update") unless Kettle::Dev::IS_CI

data/lib/kettle/dev/rakelib/spec_test.rake

@@ -7,41 +7,41 @@ require "fileutils"
 begin
   require "rake/testtask"
 
-  Rake::TestTask.new(:test) do |t|
-    t.libs << "test"
-    t.test_files = FileList["test/**/*test*.rb"]
-    t.verbose = true
+  unless Rake::Task.task_defined?(:test)
+    Rake::TestTask.new(:test) do |t|
+      t.libs << "test"
+      t.test_files = FileList["test/**/*test*.rb"]
+      t.verbose = true
+    end
+    # The test task is invoked by the coverage task, so of the two, (i.e., when outside CI),
+    #   only coverage should be registered as default.
+    Kettle::Dev.register_default("test") unless Kettle::Dev.default_registered?("coverage")
   end
-  # The test task is invoked by the coverage task, so of the two, (i.e., when outside CI),
-  #   only coverage should be registered as default.
-  Kettle::Dev.register_default("test") unless Kettle::Dev.default_registered?("coverage")
 rescue LoadError
   warn("[kettle-dev][spec_test.rake] failed to load rake/testtask") if Kettle::Dev::DEBUGGING
-  desc("test task stub")
-  task(:test) do
-    warn("NOTE: minitest isn't installed, or is disabled for #{RUBY_VERSION} in the current environment")
+  unless Rake::Task.task_defined?(:test)
+    desc("test task stub")
+    task(:test) do
+      warn("NOTE: minitest isn't installed, or is disabled for #{RUBY_VERSION} in the current environment")
+    end
   end
 end
 
 setup_spec_task = ->(default:) {
-  begin
-    require "rspec/core/rake_task"
-
-    RSpec::Core::RakeTask.new(:spec)
-    if default
-      # This takes the place of the `coverage` task if/when it isn't already registered.
-      # This is because spec and coverage run the same tests
-      # (via the coverage task invoking the test task which invokes the spec task),
-      # so we can't have both in the default task.
-      Kettle::Dev.register_default("spec") unless Kettle::Dev.default_registered?("coverage")
-    end
-  rescue LoadError
-    warn("[kettle-dev][spec_test.rake] failed to load rspec/core/rake_task") if Kettle::Dev::DEBUGGING
-    desc("spec task stub")
+  unless Rake::Task.task_defined?(:spec)
+    desc("Run RSpec code examples")
     task(:spec) do
-      warn("NOTE: rspec isn't installed, or is disabled for #{RUBY_VERSION} in the current environment")
+      sh("bundle", "exec", "kettle-test")
     end
   end
+
+  if default
+    # This takes the place of the `coverage` task if/when it isn't already registered.
+    # This is because spec and coverage run the same tests
+    # (via the coverage task invoking the test task which invokes the spec task),
+    # so we can't have both in the default task.
+    Kettle::Dev.register_default("spec") unless Kettle::Dev.default_registered?("coverage")
+  end
 }
 
 # Setup RSpec

data/lib/kettle/dev/rakelib/yard.rake

@@ -4,41 +4,26 @@
 begin
   require "yard"
 
-  # Load yard-fence rake task if available (provides yard:fence:prepare)
-  # NOTE: yard-fence >= 0.9 auto-registers its rake task when Rake is available,
-  # so this explicit require may be redundant. We keep it for backward compatibility
-  # with older yard-fence versions that don't auto-register.
-  # The yard:fence:prepare task handles:
-  # - Cleaning docs/ directory (if YARD_FENCE_CLEAN_DOCS=true)
-  # - Preparing tmp/yard-fence/ with sanitized markdown files
+  YARD::Rake::YardocTask.new(:yard) do |t|
+    # Keep .yardopts as the canonical source for included files, plugins,
+    # readme selection, and output directory. Diverging task-local file lists
+    # caused `rake yard` and `yard` to generate different docs sites.
+    t.files = []
+  end
+
   begin
-    require "yard/fence/rake_task"
-    # Only create if not already defined (yard-fence may have auto-registered)
-    Yard::Fence::RakeTask.new unless Rake::Task.task_defined?("yard:fence:prepare")
+    require "yard/fence"
+    Yard::Fence.install_rake_tasks!(:yard)
   rescue LoadError
-    # yard-fence not available or doesn't have rake_task - that's fine
+    # yard-fence not available - that's fine
   end
 
-  YARD::Rake::YardocTask.new(:yard) do |t|
-    t.files = [
-      # Source Splats (alphabetical)
-      "lib/**/*.rb",
-      "-", # source and extra docs are separated by "-"
-      # Extra Files (alphabetical)
-      "*.cff",
-      "*.md",
-      "*.txt",
-      # NOTE: checksums/**/* removed - it's in .yardignore and was causing
-      # file.<gem>.html pages to be generated for each checksum file
-      "REEK",
-      "sig/**/*.rbs",
-    ]
-
-    # No need for this, due to plugin load in .yardopts
-    # require "yard-junk/rake"
-    # YardJunk::Rake.define_task
+  begin
+    require "yard/timekeeper"
+    Yard::Timekeeper.install_rake_tasks!(:yard)
+  rescue LoadError
+    # yard-timekeeper not available - that's fine
   end
-  Kettle::Dev.register_default("yard")
 rescue LoadError
   warn("[kettle-dev][yard.rake] failed to load yard") if Kettle::Dev::DEBUGGING
   desc("(stub) yard is unavailable")

data/lib/kettle/dev/readme_backers.rb

@@ -29,7 +29,7 @@ module Kettle
       private
 
       # Emit a debug log line when kettle-dev debugging is enabled.
-      # Controlled by KETTLE_DEV_DEBUG=true (or DEBUG=true as fallback).
+      # Controlled by KETTLE_DEV_DEBUG=true.
       # @param msg [String]
       # @return [void]
       def debug_log(msg)
@@ -215,14 +215,14 @@ module Kettle
         if !backers_changed && !sponsors_changed
           if b_start == :not_found && s_start == :not_found
             ts = tag_strings
-            warn("No recognized Open Collective tags found in #{@readme_path}. Expected one or more of: " \
+            warn("No recognized Open Collective tags found in #{Kettle::Dev.display_path(@readme_path)}. Expected one or more of: " \
               "#{ts[:generic_start]}/#{ts[:generic_end]}, #{ts[:individuals_start]}/#{ts[:individuals_end]}, #{ts[:orgs_start]}/#{ts[:orgs_end]}.")
             debug_log("Missing tags: looked for #{ts}")
             # Do not exit the process during tests or library use; just return.
             return
           end
           debug_log("No changes detected after processing; Backers=#{backers.size}, Sponsors=#{sponsors.size}, ExtraTiers=#{extra_map.keys.size}")
-          puts "No changes to backers or sponsors sections in #{@readme_path}."
+          puts "No changes to backers or sponsors sections in #{Kettle::Dev.display_path(@readme_path)}."
           return
         end
 
@@ -230,7 +230,7 @@ module Kettle
         msgs = []
         msgs << "backers" if backers_changed
         msgs << "sponsors" if sponsors_changed
-        puts "Updated #{msgs.join(" and ")} section#{{true => "s", false => ""}[msgs.size > 1]} in #{@readme_path}."
+        puts "Updated #{msgs.join(" and ")} section#{{true => "s", false => ""}[msgs.size > 1]} in #{Kettle::Dev.display_path(@readme_path)}."
 
         # Compose and perform commit with mentions if in a git repo
         perform_git_commit(new_backers, new_sponsors) if git_repo? && (backers_changed || sponsors_changed)