kettle-dev 1.2.1 → 1.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cf48cdba2c3cbe1c95eab4c61a4073f7849fda6b7dbc41ec2dedaca59b414242
-  data.tar.gz: 171598b7227ced01474c97a14a8167d3c6c64785b08daeb6996e64d1ed42973d
+  metadata.gz: cad2d78d297d0e69cd016624ff87dba0c5fa4bd3af5399d7c97c4e8fcc2af82a
+  data.tar.gz: '08f58025922178025f79d3ef3004b35f9207e23764c490587ec3ed5dfc240ca5'
 SHA512:
-  metadata.gz: 224a2b34db6d14760ae6105eb67407baebb25a67d7ac1ccad37eaa01823278d3d6c68e6822430f47d986c756f232ce637df248184ec61ca7a4394df3c4ced4c8
-  data.tar.gz: f8d133803fdbcf798e05faf1749a3e03efc539d5513142bbe76da9b3954662cf043ae868b79151c0c1cb84129f15b4e3e3af7a9764e301d14134fa352ba38ff5
+  metadata.gz: 12563697c8b719fc13ded6b096fcd92266dbb98f9f8c87a21aad756bebbe2065f7dc17e2be982d1a3765a15c8c3b8cbd0eec88642fc7fb90600e1be88c4db149
+  data.tar.gz: e3ce95406792e64d08da4db003a5771c45c975155c417176e10972e13ad0e012ed006aa9193b81b1fbecc96d59edb752cba80a26a538c60f824c52228e6110e9

data/.rubocop_rspec.yml

@@ -25,6 +25,9 @@ RSpec/ExpectInHook:
 RSpec/DescribeClass:
   Exclude:
     - 'spec/examples/*'
+    - 'spec/integration/*'
+    - 'spec/system/*'
+    - 'spec/e2e/*'
 
 RSpec/MultipleMemoizedHelpers:
   Enabled: false

data/CHANGELOG.md

@@ -20,13 +20,6 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Added
 
-- Prism AST-based manipulation of ruby during templating
-  - Gemfiles
-  - gemspecs
-  - .simplecov
-- Stop rescuing Exception in certain scenarios (just StandardError)
-- Refactored logging logic and documentation
-
 ### Changed
 
 ### Deprecated
@@ -37,6 +30,43 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [1.2.3] - 2025-11-28
+
+- TAG: [v1.2.3][1.2.3t]
+- COVERAGE: 93.43% -- 4681/5010 lines in 31 files
+- BRANCH COVERAGE: 76.63% -- 1912/2495 branches in 31 files
+- 70.55% documented
+
+### Fixed
+
+- Fixed Gemfile parsing to properly deduplicate comments across multiple template runs
+  - Implemented two-pass comment deduplication: sequences first, then individual lines
+  - Magic comments (frozen_string_literal, encoding, etc.) are now properly deduplicated by content, not line position
+  - File-level comments are deduplicated while preserving leading comments attached to statements
+  - Ensures idempotent behavior when running templating multiple times on the same file
+  - Prevents accumulation of duplicate frozen_string_literal comments and comment blocks
+
+## [1.2.2] - 2025-11-27
+
+- TAG: [v1.2.2][1.2.2t]
+- COVERAGE: 93.28% -- 4596/4927 lines in 31 files
+- BRANCH COVERAGE: 76.45% -- 1883/2463 branches in 31 files
+- 70.00% documented
+
+### Added
+
+- Prism AST-based manipulation of ruby during templating
+  - Gemfiles
+  - gemspecs
+  - .simplecov
+- Stop rescuing Exception in certain scenarios (just StandardError)
+- Refactored logging logic and documentation
+- Prevent self-referential gemfile injection
+  - in Gemfiles, gemspecs, and Appraisals
+- Improve reliability of coverage and documentation stats
+  - in the changelog version heading
+  - fails hard when unable to generate stats, unless `--no-strict` provided
+
 ## [1.2.1] - 2025-11-25
 
 - TAG: [v1.2.0][1.2.0t]
@@ -1477,7 +1507,11 @@ Please file a bug if you notice a violation of semantic versioning.
   - Selecting will run the selected workflow via `act`
   - This may move to its own gem in the future.
 
-[Unreleased]: https://github.com/kettle-rb/kettle-dev/compare/v1.2.0...HEAD
+[Unreleased]: https://github.com/kettle-rb/kettle-dev/compare/v1.2.3...HEAD
+[1.2.3]: https://github.com/kettle-rb/kettle-dev/compare/v1.2.2...v1.2.3
+[1.2.3t]: https://github.com/kettle-rb/kettle-dev/releases/tag/v1.2.3
+[1.2.2]: https://github.com/kettle-rb/kettle-dev/compare/v1.2.1...v1.2.2
+[1.2.2t]: https://github.com/kettle-rb/kettle-dev/releases/tag/v1.2.2
 [1.2.0]: https://github.com/kettle-rb/kettle-dev/compare/v1.1.60...v1.2.0
 [1.2.0t]: https://github.com/kettle-rb/kettle-dev/releases/tag/v1.2.0
 [1.1.60]: https://github.com/kettle-rb/kettle-dev/compare/v1.1.59...v1.1.60

data/README.md

@@ -1026,7 +1026,7 @@ Thanks for RTFM. ☺️
 [📌gitmoji]: https://gitmoji.dev
 [📌gitmoji-img]: https://img.shields.io/badge/gitmoji_commits-%20%F0%9F%98%9C%20%F0%9F%98%8D-34495e.svg?style=flat-square
 [🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
-[🧮kloc-img]: https://img.shields.io/badge/KLOC-4.308-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-5.010-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: SECURITY.md
 [🔐security-img]: https://img.shields.io/badge/security-policy-259D6C.svg?style=flat
 [📄copyright-notice-explainer]: https://opensource.stackexchange.com/questions/5778/why-do-licenses-such-as-the-mit-license-specify-a-single-year

data/README.md.example

@@ -548,7 +548,7 @@ Thanks for RTFM. ☺️
 [📌gitmoji]: https://gitmoji.dev
 [📌gitmoji-img]: https://img.shields.io/badge/gitmoji_commits-%20%F0%9F%98%9C%20%F0%9F%98%8D-34495e.svg?style=flat-square
 [🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
-[🧮kloc-img]: https://img.shields.io/badge/KLOC-4.308-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-5.010-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: SECURITY.md
 [🔐security-img]: https://img.shields.io/badge/security-policy-259D6C.svg?style=flat
 [📄copyright-notice-explainer]: https://opensource.stackexchange.com/questions/5778/why-do-licenses-such-as-the-mit-license-specify-a-single-year

data/Rakefile.example

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# kettle-dev Rakefile v1.2.1 - 2025-11-26
+# kettle-dev Rakefile v1.2.3 - 2025-11-28
 # Ruby 2.3 (Safe Navigation) or higher required
 #
 # MIT License (see License.txt)

data/exe/kettle-changelog

@@ -50,22 +50,37 @@ end
 begin
   if ARGV.include?("-h") || ARGV.include?("--help")
     puts <<~USAGE
-      Usage: kettle-changelog
+      Usage: kettle-changelog [--no-strict]
 
       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.
 
+      Options:
+        --no-strict               Allow missing coverage and yard data (warnings only, no errors)
+
+      Environment:
+        K_CHANGELOG_STRICT=false  Disable strict mode (equivalent to --no-strict flag)
+
       Prerequisites:
-        - coverage/coverage.json present (run: K_SOUP_COV_FORMATTERS="json" bin/rspec)
+        - coverage/coverage.json present (run: bin/rake coverage to generate)
         - yard installed and available via bin/yard
+
+      By default (strict mode), if coverage.json or yard stats are missing, the script will:
+        1. Attempt to generate them by running bin/rake coverage and bin/rake yard
+        2. Fail with an error if generation fails or data is still unavailable
+
+      Use --no-strict or K_CHANGELOG_STRICT=false to allow missing data (backward compatible behavior).
     USAGE
     exit(0)
   end
 end
 
 begin
-  Kettle::Dev::ChangelogCLI.new.run
+  # Determine if strict mode is enabled (default: true)
+  strict_mode = !ARGV.include?("--no-strict") && ENV.fetch("K_CHANGELOG_STRICT", "true").downcase != "false"
+
+  Kettle::Dev::ChangelogCLI.new(strict: strict_mode).run
 rescue LoadError => e
   warn("#{script_basename}: could not load dependency: #{e.class}: #{e.message}")
   warn(e.backtrace.join("\n")) if ENV["DEBUG"]

data/kettle-dev.gemspec.example

@@ -114,10 +114,10 @@ Gem::Specification.new do |spec|
   #       and preferably a modular one (see gemfiles/modular/*.gemfile).
 
   # Dev, Test, & Release Tasks
-  spec.add_development_dependency("{KETTLE|DEV|GEM}", "~> 1.1")                           # ruby >= 2.3.0
+  spec.add_development_dependency("{KETTLE|DEV|GEM}", "~> 1.2")                           # ruby >= 2.3.0
 
   # Security
-  spec.add_development_dependency("bundler-audit", "~> 0.9.2")                      # ruby >= 2.0.0
+  spec.add_development_dependency("bundler-audit", "~> 0.9.3")                      # ruby >= 2.0.0
 
   # Tasks
   spec.add_development_dependency("rake", "~> 13.0")                                # ruby >= 2.2.0
@@ -131,7 +131,7 @@ Gem::Specification.new do |spec|
 
   # Releasing
   spec.add_development_dependency("ruby-progressbar", "~> 1.13")                    # ruby >= 0
-  spec.add_development_dependency("stone_checksums", "~> 1.0", ">= 1.0.2")          # ruby >= 2.2.0
+  spec.add_development_dependency("stone_checksums", "~> 1.0", ">= 1.0.3")          # ruby >= 2.2.0
 
   # Git integration (optional)
   # The 'git' gem is optional; kettle-dev falls back to shelling out to `git` if it is not present.

data/lib/kettle/dev/changelog_cli.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "open3"
+
 module Kettle
   module Dev
     # CLI for updating CHANGELOG.md with new version sections
@@ -11,10 +13,12 @@ module Kettle
 
       # Initialize the changelog CLI
       # Sets up paths for CHANGELOG.md and coverage.json
-      def initialize
+      # @param strict [Boolean] when true (default), require coverage and yard data; raise errors if unavailable
+      def initialize(strict: true)
         @root = Kettle::Dev::CIHelpers.project_root
         @changelog_path = File.join(@root, "CHANGELOG.md")
         @coverage_path = File.join(@root, "coverage", "coverage.json")
+        @strict = strict
       end
 
       # Main entry point to update CHANGELOG.md
@@ -215,11 +219,49 @@ module Kettle
       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]
+        if @strict
+          # Always generate fresh coverage data in strict mode
+          # Delete old coverage files to ensure we get current data
+          coverage_dir = File.dirname(@coverage_path)
+          if Dir.exist?(coverage_dir)
+            puts "Cleaning old coverage data from #{coverage_dir}..."
+            Dir.glob(File.join(coverage_dir, "*")).each do |file|
+              File.delete(file) if File.file?(file)
+            end
+          end
+
+          puts "Generating fresh coverage data by running: bin/rake coverage"
+
+          # Run bin/rake coverage to generate coverage.json
+          rake_cmd = File.join(@root, "bin", "rake")
+          unless File.executable?(rake_cmd)
+            raise "bin/rake not found or not executable; cannot generate coverage data"
+          end
+
+          # Run the command exactly as the user would run it manually
+          # The coverage task knows how to configure itself properly
+          success = system(rake_cmd, "coverage", chdir: @root)
+
+          unless success
+            raise "bin/rake coverage failed with exit status #{$?.exitstatus || "unknown"}"
+          end
+
+          puts "Coverage generation complete."
+
+          # Check if coverage.json was generated
+          unless File.file?(@coverage_path)
+            raise "Coverage JSON not found at #{@coverage_path} after running bin/rake coverage"
+          end
+        else
+          # Non-strict mode: check if coverage.json exists, warn if not
+          unless File.file?(@coverage_path)
+            warn("Coverage JSON not found at #{@coverage_path}.")
+            warn("Run: bin/rake coverage to generate it")
+            return [nil, nil]
+          end
         end
+
+        # Parse the coverage data
         data = JSON.parse(File.read(@coverage_path))
         files = data["coverage"] || {}
         file_count = 0
@@ -252,31 +294,55 @@ module Kettle
         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 JSON::ParserError => e
+        if @strict
+          raise "Failed to parse coverage JSON at #{@coverage_path}: #{e.class}: #{e.message}"
+        else
+          warn("Failed to parse coverage: #{e.class}: #{e.message}")
+          [nil, nil]
+        end
       rescue StandardError => e
-        warn("Failed to parse coverage: #{e.class}: #{e.message}")
-        [nil, nil]
+        if @strict
+          raise "Failed to get coverage data: #{e.class}: #{e.message}"
+        else
+          warn("Failed to get coverage data: #{e.class}: #{e.message}")
+          [nil, nil]
+        end
       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
+          if @strict
+            raise "bin/yard not found or not executable; ensure yard is installed via bundler"
+          else
+            warn("bin/yard not found or not executable; ensure yard is installed via bundler")
+            return
+          end
         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
+
+        begin
+          # Run bin/yard to get documentation percentage
+          out, _ = Open3.capture2(cmd, {chdir: @root})
+          # Look for a line containing e.g., "95.35% documented"
+          line = out.lines.find { |l| l =~ /\d+(?:\.\d+)?%\s+documented/ }
+
+          if line
+            line.strip
+          elsif @strict
+            raise "Could not find documented percentage in bin/yard output"
+          else
+            warn("Could not find documented percentage in bin/yard output.")
+            nil
+          end
+        rescue StandardError => e
+          if @strict
+            raise "Failed to run bin/yard: #{e.class}: #{e.message}"
+          else
+            warn("Failed to run bin/yard: #{e.class}: #{e.message}")
+            nil
+          end
         end
-      rescue StandardError => e
-        warn("Failed to run bin/yard: #{e.class}: #{e.message}")
-        nil
       end
 
       # Transform legacy release headings that include a tag suffix, e.g.:

data/lib/kettle/dev/prism_appraisals.rb

@@ -301,6 +301,51 @@ module Kettle
         statements = body.is_a?(Prism::StatementsNode) ? body.body : [body]
         statements.compact.map { |stmt| {node: stmt, inline_comments: [], leading_comments: []} }
       end
+
+      # Remove gem calls that reference the given gem name (to prevent self-dependency).
+      # Works by locating gem() call nodes within appraise blocks where the first argument matches gem_name.
+      # @param content [String] Appraisals content
+      # @param gem_name [String] the gem name to remove
+      # @return [String] modified content with self-referential gem calls removed
+      def remove_gem_dependency(content, gem_name)
+        return content if gem_name.to_s.strip.empty?
+
+        result = PrismUtils.parse_with_comments(content)
+        root = result.value
+        return content unless root&.statements&.body
+
+        out = content.dup
+
+        # Iterate through all appraise blocks
+        root.statements.body.each do |node|
+          next unless appraise_call?(node)
+          next unless node.block&.body
+
+          body_stmts = PrismUtils.extract_statements(node.block.body)
+
+          # Find gem call nodes within this appraise block where first argument matches gem_name
+          body_stmts.each do |stmt|
+            next unless stmt.is_a?(Prism::CallNode) && stmt.name == :gem
+
+            first_arg = stmt.arguments&.arguments&.first
+            arg_val = begin
+              PrismUtils.extract_literal_value(first_arg)
+            rescue StandardError
+              nil
+            end
+
+            if arg_val && arg_val.to_s == gem_name.to_s
+              # Remove this gem call from content
+              out = out.sub(stmt.slice, "")
+            end
+          end
+        end
+
+        out
+      rescue StandardError => e
+        Kettle::Dev.debug_error(e, __method__) if defined?(Kettle::Dev.debug_error)
+        content
+      end
     end
   end
 end

data/lib/kettle/dev/prism_gemfile.rb

@@ -131,6 +131,47 @@ module Kettle
         end
         dest_content
       end
+
+      # Remove gem calls that reference the given gem name (to prevent self-dependency).
+      # Works by locating gem() call nodes where the first argument matches gem_name.
+      # @param content [String] Gemfile-like content
+      # @param gem_name [String] the gem name to remove
+      # @return [String] modified content with self-referential gem calls removed
+      def remove_gem_dependency(content, gem_name)
+        return content if gem_name.to_s.strip.empty?
+
+        result = PrismUtils.parse_with_comments(content)
+        stmts = PrismUtils.extract_statements(result.value.statements)
+
+        # Find gem call nodes where first argument matches gem_name
+        gem_nodes = stmts.select do |n|
+          next false unless n.is_a?(Prism::CallNode) && n.name == :gem
+
+          first_arg = n.arguments&.arguments&.first
+          arg_val = begin
+            PrismUtils.extract_literal_value(first_arg)
+          rescue StandardError
+            nil
+          end
+          arg_val && arg_val.to_s == gem_name.to_s
+        end
+
+        # Remove each matching gem call from content
+        out = content.dup
+        gem_nodes.each do |gn|
+          # Remove the entire line(s) containing this node
+          out = out.sub(gn.slice, "")
+        end
+
+        out
+      rescue StandardError => e
+        if defined?(Kettle::Dev) && Kettle::Dev.respond_to?(:debug_error)
+          Kettle::Dev.debug_error(e, __method__)
+        else
+          Kernel.warn("[#{__method__}] #{e.class}: #{e.message}")
+        end
+        content
+      end
     end
   end
 end

data/lib/kettle/dev/source_merger.rb

@@ -48,7 +48,7 @@ module Kettle
         content =
           case strategy
           when :skip
-            src_with_reminder
+            normalize_source(src_with_reminder)
           when :replace
             normalize_source(src_with_reminder)
           when :append
@@ -81,17 +81,22 @@ module Kettle
         [before, snippet, after].join
       end
 
-      # Normalize source code while preserving formatting
+      # Normalize source code by parsing and rebuilding to deduplicate comments
       #
       # @param source [String] Ruby source code
-      # @return [String] Normalized source with trailing newline
+      # @return [String] Normalized source with trailing newline and deduplicated comments
       # @api private
       def normalize_source(source)
         parse_result = PrismUtils.parse_with_comments(source)
         return ensure_trailing_newline(source) unless parse_result.success?
 
-        # Use Prism's slice to preserve original formatting
-        ensure_trailing_newline(source)
+        # Extract and deduplicate comments
+        magic_comments = extract_magic_comments(parse_result)
+        file_leading_comments = extract_file_leading_comments(parse_result)
+        node_infos = extract_nodes_with_comments(parse_result)
+
+        # Rebuild source with deduplicated comments
+        build_source_from_nodes(node_infos, magic_comments: magic_comments, file_leading_comments: file_leading_comments)
       end
 
       def reminder_present?(content)
@@ -231,8 +236,8 @@ module Kettle
       end
 
       def prism_merge(src_content, dest_content)
-        src_result = PrismUtils.parse_with_comments(src_content)
-        dest_result = PrismUtils.parse_with_comments(dest_content)
+        src_result = Kettle::Dev::PrismUtils.parse_with_comments(src_content)
+        dest_result = Kettle::Dev::PrismUtils.parse_with_comments(dest_content)
 
         # If src parsing failed, return src unchanged to avoid losing content
         unless src_result.success?
@@ -245,11 +250,48 @@ module Kettle
 
         merged_nodes = yield(src_nodes, dest_nodes, src_result, dest_result)
 
-        # Extract magic comments from source (frozen_string_literal, etc.)
-        magic_comments = extract_magic_comments(src_result)
+        # Extract and deduplicate comments from src and dest SEPARATELY
+        # This allows sequence detection to work within each source
+        src_tuples = create_comment_tuples(src_result)
+        src_deduplicated = deduplicate_comment_sequences(src_tuples)
+
+        dest_tuples = dest_result.success? ? create_comment_tuples(dest_result) : []
+        dest_deduplicated = deduplicate_comment_sequences(dest_tuples)
+
+        # Now merge the deduplicated tuples by hash+type only (ignore line numbers)
+        seen_hash_type = Set.new
+        final_tuples = []
+
+        # Add all deduplicated src tuples
+        src_deduplicated.each do |tuple|
+          hash_val = tuple[0]
+          type = tuple[1]
+          key = [hash_val, type]
+          unless seen_hash_type.include?(key)
+            final_tuples << tuple
+            seen_hash_type << key
+          end
+        end
+
+        # Add deduplicated dest tuples that don't duplicate src (by hash+type)
+        dest_deduplicated.each do |tuple|
+          hash_val = tuple[0]
+          type = tuple[1]
+          key = [hash_val, type]
+          unless seen_hash_type.include?(key)
+            final_tuples << tuple
+            seen_hash_type << key
+          end
+        end
+
+        # Extract magic and file-level comments from final merged tuples
+        magic_comments = final_tuples
+          .select { |tuple| tuple[1] == :magic }
+          .map { |tuple| tuple[2] }
 
-        # Extract file-level leading comments (comments before first statement)
-        file_leading_comments = extract_file_leading_comments(src_result)
+        file_leading_comments = final_tuples
+          .select { |tuple| tuple[1] == :file_level }
+          .map { |tuple| tuple[2] }
 
         build_source_from_nodes(merged_nodes, magic_comments: magic_comments, file_leading_comments: file_leading_comments)
       end
@@ -257,45 +299,155 @@ module Kettle
       def extract_magic_comments(parse_result)
         return [] unless parse_result.success?
 
-        magic_comments = []
-        source_lines = parse_result.source.lines
+        tuples = create_comment_tuples(parse_result)
+        deduplicated = deduplicate_comment_sequences(tuples)
 
-        # Magic comments appear at the very top of the file (possibly after shebang)
-        # They must be on the first or second line
-        source_lines.first(2).each do |line|
-          stripped = line.strip
-          # Check for shebang
-          if stripped.start_with?("#!")
-            magic_comments << line.rstrip
-          # Check for magic comments like frozen_string_literal, encoding, etc.
-          elsif stripped.start_with?("#") &&
-              (stripped.include?("frozen_string_literal:") ||
-               stripped.include?("encoding:") ||
-               stripped.include?("warn_indent:") ||
-               stripped.include?("shareable_constant_value:"))
-            magic_comments << line.rstrip
+        # Filter to only magic comments and return their text
+        deduplicated
+          .select { |tuple| tuple[1] == :magic }
+          .map { |tuple| tuple[2] }
+      end
+
+      # Create a tuple for each comment: [hash, type, text, line_number]
+      # where type is one of: :magic, :file_level, :leading
+      # (inline comments are handled with their associated statements)
+      def create_comment_tuples(parse_result)
+        return [] unless parse_result.success?
+
+        statements = PrismUtils.extract_statements(parse_result.value.statements)
+        first_stmt_line = statements.any? ? statements.first.location.start_line : Float::INFINITY
+
+        tuples = []
+
+        parse_result.comments.each do |comment|
+          comment_line = comment.location.start_line
+          comment_text = comment.slice.strip
+
+          # Determine comment type - magic comments are identified by content, not line number
+          type = if is_magic_comment?(comment_text)
+            :magic
+          elsif comment_line < first_stmt_line
+            :file_level
+          else
+            # This will be handled as a leading or inline comment for a statement
+            :leading
+          end
+
+          # Create hash from normalized comment text (ignoring trailing whitespace)
+          comment_hash = comment_text.hash
+
+          tuples << [comment_hash, type, comment.slice.rstrip, comment_line]
+        end
+
+        tuples
+      end
+
+      def is_magic_comment?(text)
+        text.include?("frozen_string_literal:") ||
+          text.include?("encoding:") ||
+          text.include?("warn_indent:") ||
+          text.include?("shareable_constant_value:")
+      end
+
+      # Two-pass deduplication:
+      # Pass 1: Deduplicate multi-line sequences
+      # Pass 2: Deduplicate single-line duplicates
+      def deduplicate_comment_sequences(tuples)
+        return [] if tuples.empty?
+
+        # Group tuples by type
+        by_type = tuples.group_by { |tuple| tuple[1] }
+
+        result = []
+
+        [:magic, :file_level, :leading].each do |type|
+          type_tuples = by_type[type] || []
+          next if type_tuples.empty?
+
+          # Pass 1: Remove duplicate sequences
+          after_pass1 = deduplicate_sequences_pass1(type_tuples)
+
+          # Pass 2: Remove single-line duplicates
+          after_pass2 = deduplicate_singles_pass2(after_pass1)
+
+          result.concat(after_pass2)
+        end
+
+        result
+      end
+
+      # Pass 1: Find and remove duplicate multi-line comment sequences
+      # A sequence is defined by consecutive comments (ignoring blank lines in between)
+      def deduplicate_sequences_pass1(tuples)
+        return tuples if tuples.length <= 1
+
+        # Group tuples into sequences (consecutive comments, allowing gaps for blank lines)
+        sequences = []
+        current_seq = []
+        prev_line = nil
+
+        tuples.each do |tuple|
+          line_num = tuple[3]
+
+          # If this is consecutive with previous (allowing reasonable gaps for blank lines)
+          if prev_line.nil? || (line_num - prev_line) <= 3
+            current_seq << tuple
+          else
+            # Start new sequence
+            sequences << current_seq if current_seq.any?
+            current_seq = [tuple]
+          end
+
+          prev_line = line_num
+        end
+        sequences << current_seq if current_seq.any?
+
+        # Find duplicate sequences by comparing hash signatures
+        seen_seq_signatures = Set.new
+        unique_tuples = []
+
+        sequences.each do |seq|
+          # Create signature from hashes and sequence length
+          seq_signature = seq.map { |t| t[0] }.join(",")
+
+          unless seen_seq_signatures.include?(seq_signature)
+            seen_seq_signatures << seq_signature
+            unique_tuples.concat(seq)
           end
         end
 
-        magic_comments
+        unique_tuples
+      end
+
+      # Pass 2: Remove single-line duplicates from already sequence-deduplicated tuples
+      def deduplicate_singles_pass2(tuples)
+        return tuples if tuples.length <= 1
+
+        seen_hashes = Set.new
+        unique_tuples = []
+
+        tuples.each do |tuple|
+          comment_hash = tuple[0]
+
+          unless seen_hashes.include?(comment_hash)
+            seen_hashes << comment_hash
+            unique_tuples << tuple
+          end
+        end
+
+        unique_tuples
       end
 
       def extract_file_leading_comments(parse_result)
         return [] unless parse_result.success?
 
-        statements = PrismUtils.extract_statements(parse_result.value.statements)
-        return [] if statements.empty?
+        tuples = create_comment_tuples(parse_result)
+        deduplicated = deduplicate_comment_sequences(tuples)
 
-        first_stmt = statements.first
-        first_stmt_line = first_stmt.location.start_line
-
-        # Extract file-level comments that appear after magic comments (line 1-2)
-        # but before the first executable statement. These are typically documentation
-        # comments describing the file's purpose.
-        parse_result.comments.select do |comment|
-          comment.location.start_line > 2 &&
-            comment.location.start_line < first_stmt_line
-        end.map { |comment| comment.slice.rstrip }
+        # Filter to only file-level comments and return their text
+        deduplicated
+          .select { |tuple| tuple[1] == :file_level }
+          .map { |tuple| tuple[2] }
       end
 
       def extract_nodes_with_comments(parse_result)
@@ -358,8 +510,6 @@ module Kettle
       end
 
       def build_source_from_nodes(node_infos, magic_comments: [], file_leading_comments: [])
-        return "" if node_infos.empty?
-
         lines = []
 
         # Add magic comments at the top (frozen_string_literal, etc.)
@@ -371,9 +521,16 @@ module Kettle
         # Add file-level leading comments (comments before first statement)
         if file_leading_comments.any?
           lines.concat(file_leading_comments)
-          lines << "" # Add blank line after file-level comments
+          # Only add blank line if there are statements following
+          lines << "" if node_infos.any?
         end
 
+        # If there are no statements and no comments, return empty string
+        return "" if node_infos.empty? && lines.empty?
+
+        # If there are only comments and no statements, return the comments
+        return lines.join("\n") if node_infos.empty?
+
         node_infos.each do |node_info|
           # Add blank lines before this statement (for visual grouping)
           blank_lines = node_info[:blank_lines_before] || 0
@@ -435,7 +592,14 @@ module Kettle
       def restore_custom_leading_comments(dest_content, merged_content)
         block = leading_comment_block(dest_content)
         return merged_content if block.strip.empty?
-        return merged_content if merged_content.start_with?(block)
+
+        # Check if the merged content already starts with this block
+        # Use normalized comparison to handle whitespace differences
+        merged_leading = leading_comment_block(merged_content)
+
+        # If merged already has the same or more comprehensive leading comments, don't add
+        return merged_content if merged_leading.strip == block.strip
+        return merged_content if merged_content.include?(block.strip)
 
         # Insert after shebang / frozen string literal comments (same place reminder goes)
         insertion_index = reminder_insertion_index(merged_content)

data/lib/kettle/dev/template_helpers.rb

@@ -298,6 +298,19 @@ module Kettle
           end
         end
 
+        # Apply self-dependency removal for all gem-related files
+        # This ensures we don't introduce a self-dependency when templating
+        begin
+          meta = gemspec_metadata
+          gem_name = meta[:gem_name]
+          if gem_name && !gem_name.to_s.empty?
+            content = remove_self_dependency(content, gem_name, dest_path)
+          end
+        rescue StandardError => e
+          Kettle::Dev.debug_error(e, __method__)
+          # If metadata extraction or removal fails, proceed with content as-is
+        end
+
         write_file(dest_path, content)
         begin
           # Ensure executable bit for git hook scripts when writing under .git-hooks
@@ -342,6 +355,38 @@ module Kettle
         content
       end
 
+      # Remove self-referential gem dependencies from content based on file type.
+      # Applies to gemspec, Gemfile, modular gemfiles, Appraisal.root.gemfile, and Appraisals.
+      # @param content [String] file content
+      # @param gem_name [String] the gem name to remove
+      # @param file_path [String] path to the file (used to determine type)
+      # @return [String] content with self-dependencies removed
+      def remove_self_dependency(content, gem_name, file_path)
+        return content if gem_name.to_s.strip.empty?
+
+        basename = File.basename(file_path.to_s)
+
+        begin
+          case basename
+          when /\.gemspec$/
+            # Use PrismGemspec for gemspec files
+            Kettle::Dev::PrismGemspec.remove_spec_dependency(content, gem_name)
+          when "Gemfile", "Appraisal.root.gemfile", /\.gemfile$/
+            # Use PrismGemfile for Gemfile-like files
+            Kettle::Dev::PrismGemfile.remove_gem_dependency(content, gem_name)
+          when "Appraisals"
+            # Use PrismAppraisals for Appraisals files
+            Kettle::Dev::PrismAppraisals.remove_gem_dependency(content, gem_name)
+          else
+            # Return content unchanged for unknown file types
+            content
+          end
+        rescue StandardError => e
+          Kettle::Dev.debug_error(e, __method__)
+          content
+        end
+      end
+
       # Copy a directory tree, prompting before creating or overwriting.
       # @return [void]
       def copy_dir_with_prompt(src_dir, dest_dir)

data/lib/kettle/dev/version.rb

@@ -6,7 +6,7 @@ module Kettle
     module Version
       # The gem version.
       # @return [String]
-      VERSION = "1.2.1"
+      VERSION = "1.2.3"
 
       module_function
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kettle-dev
 version: !ruby/object:Gem::Version
-  version: 1.2.1
+  version: 1.2.3
 platform: ruby
 authors:
 - Peter H. Boling
@@ -57,14 +57,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.9.2
+        version: 0.9.3
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.9.2
+        version: 0.9.3
 - !ruby/object:Gem::Dependency
   name: require_bench
   requirement: !ruby/object:Gem::Requirement
@@ -142,7 +142,7 @@ dependencies:
         version: '1.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.0.2
+        version: 1.0.3
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -152,7 +152,7 @@ dependencies:
         version: '1.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.0.2
+        version: 1.0.3
 - !ruby/object:Gem::Dependency
   name: gitmoji-regex
   requirement: !ruby/object:Gem::Requirement
@@ -414,10 +414,10 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://kettle-dev.galtzo.com/
-  source_code_uri: https://github.com/kettle-rb/kettle-dev/tree/v1.2.1
-  changelog_uri: https://github.com/kettle-rb/kettle-dev/blob/v1.2.1/CHANGELOG.md
+  source_code_uri: https://github.com/kettle-rb/kettle-dev/tree/v1.2.3
+  changelog_uri: https://github.com/kettle-rb/kettle-dev/blob/v1.2.3/CHANGELOG.md
   bug_tracker_uri: https://github.com/kettle-rb/kettle-dev/issues
-  documentation_uri: https://www.rubydoc.info/gems/kettle-dev/1.2.1
+  documentation_uri: https://www.rubydoc.info/gems/kettle-dev/1.2.3
   funding_uri: https://github.com/sponsors/pboling
   wiki_uri: https://github.com/kettle-rb/kettle-dev/wiki
   news_uri: https://www.railsbling.com/tags/kettle-dev