kettle-dev 1.1.60 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a2c485db803ad10d4d7eb1331a8ed30ce0744c0a045ee768697bfa5098f44707
-  data.tar.gz: c60544c59a2bd2b0af6d80aaa070055ca74d3a88e8e2b53cd2c94050da03e89e
+  metadata.gz: c5ef625cbc6016859cd2c88105ce957e3719465cee97356df1fc77a30c8504c1
+  data.tar.gz: e18d15a0d1da90c31991b4b6601b698633dad3e377145724f8fb277ec7b2a75a
 SHA512:
-  metadata.gz: b7f36fd6f1cd77538e0ebcff3ae9c96136594a242f95d15aaa4690f84dcdd376efa3be923b26bb6bad6176c5addaa88c18fdd1d38329c9065535c9666897048c
-  data.tar.gz: d881e65d43eeccd20f540c135821402b046b8601e130d16204e6c7a501d092270af97ebce0a7757345d3c4cf340b22b78e6858b80ff0f6863fe3dcbba93f7e4c
+  metadata.gz: 227cb01388512c937d73fddf46deac2edf2b062f93a97b8e788ac0af4e21f8bd1b3a941dc4bf8eabfd5b494401e935e08a8d28d10fc1954b728e7148953e531b
+  data.tar.gz: 336fe91aab36fd2ca958967fbc3cfaaa2d6cea7dbb5b1e4d63882526b1271561920d41c016f301b93eb533cb636d252e923882859c9be58fbe4bd586b29d870d

data/CHANGELOG.md

@@ -30,6 +30,18 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [1.2.0] - 2025-11-25
+
+- TAG: [v1.2.0][1.2.0t]
+- COVERAGE: 94.38% -- 4066/4308 lines in 26 files
+- BRANCH COVERAGE: 78.81% -- 1674/2124 branches in 26 files
+- 69.14% documented
+
+### Changed
+
+- Source merging switched from Regex-based string manipulation to Prism AST-based manipulation
+  - Comments are preserved in the resulting file
+
 ## [1.1.60] - 2025-11-23
 
 - TAG: [v1.1.60][1.1.60t]
@@ -1458,7 +1470,9 @@ 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.1.60...HEAD
+[Unreleased]: https://github.com/kettle-rb/kettle-dev/compare/v1.2.0...HEAD
+[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
 [1.1.60t]: https://github.com/kettle-rb/kettle-dev/releases/tag/v1.1.60
 [1.1.59]: https://github.com/kettle-rb/kettle-dev/compare/v1.1.58...v1.1.59

data/Gemfile

@@ -12,6 +12,9 @@ git_source(:gitlab) { |repo_name| "https://gitlab.com/#{repo_name}" }
 # Include dependencies from <gem name>.gemspec
 gemspec
 
+# Templating
+eval_gemfile "gemfiles/modular/templating.gemfile"
+
 # Debugging
 eval_gemfile "gemfiles/modular/debug.gemfile"
 

data/Gemfile.example

@@ -12,6 +12,9 @@ git_source(:gitlab) { |repo_name| "https://gitlab.com/#{repo_name}" }
 # Include dependencies from <gem name>.gemspec
 gemspec
 
+# Templating
+eval_gemfile "gemfiles/modular/templating.gemfile"
+
 # Debugging
 eval_gemfile "gemfiles/modular/debug.gemfile"
 

data/README.md

@@ -574,41 +574,84 @@ What it does:
   - Stages and commits any bootstrap changes with message: `🎨 Template bootstrap by kettle-dev-setup v<version>`.
   - Executes `bin/rake kettle:dev:install` with the parsed passthrough args.
 
+### Template Manifest and AST Strategies
+
+`kettle:dev:template` looks at `template_manifest.yml` to determine how each file should be updated. Each entry has a `path` (exact file or glob) and a `strategy`:
+
+| Strategy | Behavior |
+| --- | --- |
+| `skip` | Legacy behavior: template content is copied with token replacements and any bespoke merge logic already in place. |
+| `replace` | Template AST replaces the destination outside of `kettle-dev:freeze` sections. |
+| `append` | Only missing AST nodes (e.g., `gem` or `task` declarations) are appended; existing nodes remain untouched. |
+| `merge` | Destination nodes are updated in-place using the template AST (used for `Gemfile`, `*.gemspec`, and `Rakefile`). |
+
+All Ruby files receive this reminder (inserted after shebang/frozen-string-literal lines):
+
+```
+# To force retention during kettle-dev templating:
+#     kettle-dev:freeze
+#     # ... your code
+#     kettle-dev:unfreeze
+```
+
+Wrap any code you never want rewritten between `kettle-dev:freeze` / `kettle-dev:unfreeze` comments. When an AST merge fails, the task emits an error asking you to file an issue at https://github.com/kettle-rb/kettle-dev/issues and then aborts—there is no regex fallback.
+
+### Template Example
+
+Here is an example `template_manifest.yml`:
+
+```yaml
+# For each file or glob, specify a strategy for how it should be managed.
+# See https://github.com/kettle-rb/kettle-dev/blob/main/docs/README.md#template-manifest-and-ast-strategies
+# for details on each strategy.
+files:
+  - path: "Gemfile"
+    strategy: "merge"
+  - path: "*.gemspec"
+    strategy: "merge"
+  - path: "Rakefile"
+    strategy: "merge"
+  - path: "README.md"
+    strategy: "replace"
+  - path: ".env.local"
+    strategy: "skip"
+```
+
 ### Open Collective README updater
 
 - Script: `exe/kettle-readme-backers` (run as `kettle-readme-backers`)
 - Purpose: Updates README sections for Open Collective backers (individuals) and sponsors (organizations) by fetching live data from your collective.
 - Tags updated in README.md (first match wins for backers):
-  - The default tag prefix is `OPENCOLLECTIVE`, and it is configurable:
-    - ENV: `KETTLE_DEV_BACKER_README_OSC_TAG="OPENCOLLECTIVE"`
-    - YAML (.opencollective.yml): `readme-osc-tag: "OPENCOLLECTIVE"`
-    - The resulting markers become: `<!-- <TAG>:START --> … <!-- <TAG>:END -->`, `<!-- <TAG>-INDIVIDUALS:START --> … <!-- <TAG>-INDIVIDUALS:END -->`, and `<!-- <TAG>-ORGANIZATIONS:START --> … <!-- <TAG>-ORGANIZATIONS:END -->`.
-    - ENV overrides YAML.
-  - Backers (Individuals): `<!-- <TAG>:START --> … <!-- <TAG>:END -->` or `<!-- <TAG>-INDIVIDUALS:START --> … <!-- <TAG>-INDIVIDUALS:END -->`
-  - Sponsors (Organizations): `<!-- <TAG>-ORGANIZATIONS:START --> … <!-- <TAG>-ORGANIZATIONS:END -->`
+    - The default tag prefix is `OPENCOLLECTIVE`, and it is configurable:
+        - ENV: `KETTLE_DEV_BACKER_README_OSC_TAG="OPENCOLLECTIVE"`
+        - YAML (.opencollective.yml): `readme-osc-tag: "OPENCOLLECTIVE"`
+        - The resulting markers become: `<!-- <TAG>:START --> … <!-- <TAG>:END -->`, `<!-- <TAG>-INDIVIDUALS:START --> … <!-- <TAG>-INDIVIDUALS:END -->`, and `<!-- <TAG>-ORGANIZATIONS:START --> … <!-- <TAG>-ORGANIZATIONS:END -->`.
+        - ENV overrides YAML.
+    - Backers (Individuals): `<!-- <TAG>:START --> … <!-- <TAG>:END -->` or `<!-- <TAG>-INDIVIDUALS:START --> … <!-- <TAG>-INDIVIDUALS:END -->`
+    - Sponsors (Organizations): `<!-- <TAG>-ORGANIZATIONS:START --> … <!-- <TAG>-ORGANIZATIONS:END -->`
 - Handle resolution:
-  1. `OPENCOLLECTIVE_HANDLE` environment variable, if set
-  2. `opencollective.yml` in the project root (e.g., `collective: "kettle-rb"` in this repo)
+    1. `OPENCOLLECTIVE_HANDLE` environment variable, if set
+    2. `opencollective.yml` in the project root (e.g., `collective: "kettle-rb"` in this repo)
 - Usage:
-  - `exe/kettle-readme-backers`
-  - `OPENCOLLECTIVE_HANDLE=my-collective exe/kettle-readme-backers`
+    - `exe/kettle-readme-backers`
+    - `OPENCOLLECTIVE_HANDLE=my-collective exe/kettle-readme-backers`
 - Behavior:
-  - Writes to README.md only if content between the tags would change.
-  - If neither the backers nor sponsors tags are present, prints a helpful warning and exits with status 2.
-  - When there are no entries, inserts a friendly placeholder: "No backers yet. Be the first!" or "No sponsors yet. Be the first!".
-  - When updates are written and the repository is a git work tree, the script stages README.md and commits with a message thanking new backers and subscribers, including mentions for any newly added backers and subscribers (GitHub @handles when their website/profile is a github.com URL; otherwise their name).
-  - Customize the commit subject via env var: `KETTLE_README_BACKERS_COMMIT_SUBJECT="💸 Thanks 🙏 to our new backers 🎒 and subscribers 📜"`.
-    - Or via .opencollective.yml: set `readme-backers-commit-subject: "💸 Thanks 🙏 to our new backers 🎒 and subscribers 📜"`.
-    - Precedence: ENV overrides .opencollective.yml; if neither is set, a sensible default is used.
-    - Note: When used with the provided `.git-hooks`, the subject should start with a gitmoji character (see [gitmoji][📌gitmoji]).
+    - Writes to README.md only if content between the tags would change.
+    - If neither the backers nor sponsors tags are present, prints a helpful warning and exits with status 2.
+    - When there are no entries, inserts a friendly placeholder: "No backers yet. Be the first!" or "No sponsors yet. Be the first!".
+    - When updates are written and the repository is a git work tree, the script stages README.md and commits with a message thanking new backers and subscribers, including mentions for any newly added backers and subscribers (GitHub @handles when their website/profile is a github.com URL; otherwise their name).
+    - Customize the commit subject via env var: `KETTLE_README_BACKERS_COMMIT_SUBJECT="💸 Thanks 🙏 to our new backers 🎒 and subscribers 📜"`.
+        - Or via .opencollective.yml: set `readme-backers-commit-subject: "💸 Thanks 🙏 to our new backers 🎒 and subscribers 📜"`.
+        - Precedence: ENV overrides .opencollective.yml; if neither is set, a sensible default is used.
+        - Note: When used with the provided `.git-hooks`, the subject should start with a gitmoji character (see [gitmoji][📌gitmoji]).
 - Tip:
-  - Run this locally before committing to keep your README current, or schedule it in CI to refresh periodically.
-  - It runs automatically on a once-a-week schedule by the .github/workflows/opencollective.yml workflow that is part of the kettle-dev template.
+    - Run this locally before committing to keep your README current, or schedule it in CI to refresh periodically.
+    - It runs automatically on a once-a-week schedule by the .github/workflows/opencollective.yml workflow that is part of the kettle-dev template.
 - Authentication requirement:
-  - When running in CI with the provided workflow, you must provide an organization-level Actions secret named `README_UPDATER_TOKEN`.
-    - Create it under your GitHub organization settings: `https://github.com/organizations/<YOUR_ORG>/settings/secrets/actions`.
-    - The updater will look for `REPO` or `GITHUB_REPOSITORY` (both usually set by GitHub Actions) to infer `<YOUR_ORG>` for guidance.
-    - If `README_UPDATER_TOKEN` is missing, the tool prints a helpful error to STDERR and aborts, including a direct link to the expected org settings page.
+    - When running in CI with the provided workflow, you must provide an organization-level Actions secret named `README_UPDATER_TOKEN`.
+        - Create it under your GitHub organization settings: `https://github.com/organizations/<YOUR_ORG>/settings/secrets/actions`.
+        - The updater will look for `REPO` or `GITHUB_REPOSITORY` (both usually set by GitHub Actions) to infer `<YOUR_ORG>` for guidance.
+        - If `README_UPDATER_TOKEN` is missing, the tool prints a helpful error to STDERR and aborts, including a direct link to the expected org settings page.
 
 ## 🦷 FLOSS Funding
 
@@ -679,6 +722,12 @@ We [![Keep A Changelog][📗keep-changelog-img]][📗keep-changelog] so if you m
 
 See [CONTRIBUTING.md][🤝contributing] for more detailed instructions.
 
+### Roadmap
+
+- [ ] Template the RSpec test harness.
+- [ ] Enhance gitlab pipeline configuration.
+- [ ] Add focused, packaged, named, templating strategies, allowing, for example, only refreshing the Appraisals related template files.
+
 ### 🚀 Release Instructions
 
 See [CONTRIBUTING.md][🤝contributing].

data/Rakefile.example

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

data/gemfiles/modular/style.gemfile.example

@@ -13,7 +13,7 @@ gem "rubocop-on-rbs", "~> 1.8"                    # ruby >= 3.1.0
 gem "benchmark", "~> 0.4", ">= 0.4.1" # Removed from Std Lib in Ruby 3.5
 
 if ENV.fetch("RUBOCOP_LTS_LOCAL", "false").casecmp("true").zero?
-  home = ENV["HOME"]
+  home = ENV["HOME"] || Dir.home
   gem "rubocop-lts", path: "#{home}/src/rubocop-lts/rubocop-lts"
   gem "rubocop-lts-rspec", path: "#{home}/src/rubocop-lts/rubocop-lts-rspec"
   gem "{RUBOCOP|RUBY|GEM}", path: "#{home}/src/rubocop-lts/{RUBOCOP|RUBY|GEM}"

data/gemfiles/modular/templating.gemfile

@@ -0,0 +1,3 @@
+# Ruby parsing for advanced templating
+gem "prism", "~> 1.6"
+gem "unparser", "~> 0.8", ">= 0.8.1"

data/lib/kettle/dev/appraisals_ast_merger.rb

@@ -0,0 +1,383 @@
+# frozen_string_literal: true
+
+require "prism"
+require "kettle/dev/prism_utils"
+
+module Kettle
+  module Dev
+    # AST-driven merger for Appraisals files using Prism.
+    # Preserves all comments: preamble headers, block headers, and inline comments.
+    # Uses PrismUtils for shared Prism AST operations.
+    module AppraisalsAstMerger
+      TRACKED_METHODS = [:gem, :eval_gemfile, :gemfile].freeze
+
+      module_function
+
+      # Merge template and destination Appraisals files preserving comments
+      #
+      # Merges appraise blocks by name, preserving:
+      # - Preamble comments (deduplicated)
+      # - Block headers (comments before each appraise block)
+      # - Inline comments on gem/eval_gemfile statements
+      # - Leading comments before statements
+      #
+      # @param template_content [String] Template Appraisals content
+      # @param dest_content [String] Destination Appraisals content
+      # @return [String] Merged Appraisals content with preserved comments
+      # @example
+      #   AppraisalsAstMerger.merge(
+      #     'appraise "rails-7" { gem "rails", "~> 7.0" }',
+      #     'appraise "custom" { gem "foo" }'
+      #   )
+      def merge(template_content, dest_content)
+        template_content ||= ""
+        dest_content ||= ""
+
+        return template_content if dest_content.strip.empty?
+        return dest_content if template_content.strip.empty?
+
+        # Parse with Prism to get AST and comments
+        tmpl_result = PrismUtils.parse_with_comments(template_content)
+        dest_result = PrismUtils.parse_with_comments(dest_content)
+
+        # Extract preamble and blocks with their headers
+        tmpl_preamble, tmpl_blocks = extract_blocks(tmpl_result, template_content)
+        dest_preamble, dest_blocks = extract_blocks(dest_result, dest_content)
+
+        # Merge preambles
+        merged_preamble = merge_preambles(tmpl_preamble, dest_preamble)
+
+        # Merge blocks
+        merged_blocks = merge_blocks(tmpl_blocks, dest_blocks, tmpl_result, dest_result)
+
+        # Build output
+        build_output(merged_preamble, merged_blocks)
+      end
+
+      def extract_blocks(parse_result, source_content)
+        root = parse_result.value
+        return [[], []] unless root&.statements&.body
+
+        source_lines = source_content.lines
+        blocks = []
+        first_appraise_line = nil
+
+        # Find all appraise blocks
+        root.statements.body.each do |node|
+          if appraise_call?(node)
+            first_appraise_line ||= node.location.start_line
+            name = extract_appraise_name(node)
+            next unless name
+
+            # Extract block header (comments immediately before this block)
+            block_header = extract_block_header(node, source_lines, blocks)
+
+            blocks << {
+              node: node,
+              name: name,
+              header: block_header,
+            }
+          end
+        end
+
+        # Preamble is all comments before first appraise block
+        preamble_comments = if first_appraise_line
+          parse_result.comments.select { |c| c.location.start_line < first_appraise_line }
+        else
+          parse_result.comments
+        end
+
+        # Filter out comments that are part of block headers
+        block_header_lines = blocks.flat_map { |b| b[:header].lines.map { |l| l.strip } }.to_set
+        preamble_comments = preamble_comments.reject { |c| block_header_lines.include?(c.slice.strip) }
+
+        [preamble_comments, blocks]
+      end
+
+      def appraise_call?(node)
+        PrismUtils.block_call_to?(node, :appraise)
+      end
+
+      def extract_appraise_name(node)
+        return unless node.is_a?(Prism::CallNode)
+        # Use PrismUtils for extracting literal values
+        PrismUtils.extract_literal_value(node.arguments&.arguments&.first)
+      end
+
+      def merge_preambles(tmpl_comments, dest_comments)
+        tmpl_lines = tmpl_comments.map { |c| c.slice.strip }
+        dest_lines = dest_comments.map { |c| c.slice.strip }
+
+        # Remove magic comments from dest if template has them
+        magic_pattern = /^#.*frozen_string_literal/
+        if tmpl_lines.any? { |line| line.match?(magic_pattern) }
+          dest_lines.reject! { |line| line.match?(magic_pattern) }
+        end
+
+        # Merge unique lines (case-insensitive), template first
+        merged = []
+        seen = Set.new
+
+        (tmpl_lines + dest_lines).each do |line|
+          normalized = line.downcase
+          unless seen.include?(normalized)
+            merged << line
+            seen << normalized
+          end
+        end
+
+        merged
+      end
+
+      def extract_block_header(node, source_lines, previous_blocks)
+        # Get the line number where this block starts (1-indexed from Prism)
+        begin_line = node.location.start_line
+
+        # Find the end of the previous block or start of file
+        min_line = if previous_blocks.empty?
+          1
+        else
+          previous_blocks.last[:node].location.end_line + 1
+        end
+
+        # Convert to 0-indexed and look at the line before the block
+        check_line = begin_line - 2  # e.g., if block is on line 2 (1-indexed), check line 0 (0-indexed, which is line 1 in file)
+
+        # Look backwards from the block start to find contiguous comment lines
+        header_lines = []
+
+        while check_line >= 0 && (check_line + 1) >= min_line
+          line = source_lines[check_line]
+          break unless line
+
+          # Stop at empty line
+          if line.strip.empty?
+            break
+          elsif line.lstrip.start_with?("#")
+            header_lines.unshift(line)
+            check_line -= 1
+          else
+            # Non-comment, non-blank line - stop
+            break
+          end
+        end
+
+        header_lines.join
+      rescue StandardError => e
+        Kettle::Dev.debug_error(e, __method__) if defined?(Kettle::Dev.debug_error)
+        ""
+      end
+
+      def merge_blocks(template_blocks, dest_blocks, tmpl_result, dest_result)
+        merged = []
+        dest_by_name = dest_blocks.each_with_object({}) { |b, h| h[b[:name]] = b }
+        template_names = template_blocks.map { |b| b[:name] }.to_set
+
+        # Track which dest blocks we've already placed
+        placed_dest = Set.new
+
+        # For each template block, merge it and insert any dest-only blocks that come before it
+        template_blocks.each_with_index do |tmpl_block, idx|
+          name = tmpl_block[:name]
+
+          # Find dest-only blocks that should come before this template block
+          # (i.e., blocks that appear in dest before this shared block)
+          if idx == 0 || dest_by_name[name]
+            # For first template block or when we have a dest version of this block,
+            # check if there are dest-only blocks to insert before it
+            dest_blocks.each do |db|
+              next if template_names.include?(db[:name])
+              next if placed_dest.include?(db[:name])
+
+              # Check if this dest-only block comes before current shared block in dest
+              dest_idx_of_shared = dest_blocks.index { |b| b[:name] == name }
+              dest_idx_of_only = dest_blocks.index { |b| b[:name] == db[:name] }
+
+              if dest_idx_of_only && dest_idx_of_shared && dest_idx_of_only < dest_idx_of_shared
+                merged << db
+                placed_dest << db[:name]
+              end
+            end
+          end
+
+          # Now add the template block (merged or template-only)
+          dest_block = dest_by_name[name]
+          if dest_block
+            # Merge this block
+            merged_header = merge_block_headers(tmpl_block[:header], dest_block[:header])
+            merged_statements = merge_block_statements(
+              tmpl_block[:node].block.body,
+              dest_block[:node].block.body,
+              dest_result,
+            )
+            merged << {
+              name: name,
+              header: merged_header,
+              node: tmpl_block[:node],
+              statements: merged_statements,
+            }
+            placed_dest << name
+          else
+            # Template-only block
+            merged << tmpl_block
+          end
+        end
+
+        # Add any remaining destination-only blocks that haven't been placed
+        dest_blocks.each do |dest_block|
+          next if placed_dest.include?(dest_block[:name])
+          next if template_names.include?(dest_block[:name])
+          merged << dest_block
+        end
+
+        merged
+      end
+
+      def merge_block_headers(tmpl_header, dest_header)
+        tmpl_lines = tmpl_header.to_s.lines.map(&:strip).reject(&:empty?)
+        dest_lines = dest_header.to_s.lines.map(&:strip).reject(&:empty?)
+
+        # Merge without duplicates (case-insensitive comparison), template first
+        merged = []
+        seen = Set.new
+
+        (tmpl_lines + dest_lines).each do |line|
+          normalized = line.downcase
+          unless seen.include?(normalized)
+            merged << line
+            seen << normalized
+          end
+        end
+
+        return "" if merged.empty?
+        merged.join("\n") + "\n"
+      end
+
+      def merge_block_statements(tmpl_body, dest_body, dest_result)
+        tmpl_stmts = PrismUtils.extract_statements(tmpl_body)
+        dest_stmts = PrismUtils.extract_statements(dest_body)
+
+        # Build statement keys for both
+        tmpl_keys = Set.new
+        tmpl_key_to_node = {}
+        tmpl_stmts.each do |stmt|
+          key = statement_key(stmt)
+          if key
+            tmpl_keys << key
+            tmpl_key_to_node[key] = stmt
+          end
+        end
+
+        dest_keys = Set.new
+        dest_stmts.each do |stmt|
+          key = statement_key(stmt)
+          dest_keys << key if key
+        end
+
+        # Process dest statements in order, preserving their position and comments
+        merged = []
+        dest_stmts.each_with_index do |dest_stmt, idx|
+          dest_key = statement_key(dest_stmt)
+
+          if dest_key && tmpl_keys.include?(dest_key)
+            # Shared statement - use template version but preserve dest position
+            # Add it with no comments (template version is canonical)
+            merged << {node: tmpl_key_to_node[dest_key], inline_comments: [], leading_comments: [], shared: true, key: dest_key}
+          else
+            # Dest-only statement - preserve with all comments
+            inline_comments = PrismUtils.inline_comments_for_node(dest_result, dest_stmt)
+
+            prev_stmt = (idx > 0) ? dest_stmts[idx - 1] : nil
+            leading_comments = PrismUtils.find_leading_comments(dest_result, dest_stmt, prev_stmt, dest_body)
+
+            merged << {node: dest_stmt, inline_comments: inline_comments, leading_comments: leading_comments, shared: false}
+          end
+        end
+
+        # Add template-only statements (those not in dest) at the end
+        tmpl_stmts.each do |tmpl_stmt|
+          tmpl_key = statement_key(tmpl_stmt)
+          unless tmpl_key && dest_keys.include?(tmpl_key)
+            merged << {node: tmpl_stmt, inline_comments: [], leading_comments: [], shared: false}
+          end
+        end
+
+        # Clean up - remove the tracking fields
+        merged.each do |item|
+          item.delete(:shared)
+          item.delete(:key)
+        end
+
+        merged
+      end
+
+      def statement_key(node)
+        # Use PrismUtils for statement key generation with Appraisals-specific tracked methods
+        PrismUtils.statement_key(node, tracked_methods: TRACKED_METHODS)
+      end
+
+      def build_output(preamble_lines, blocks)
+        output = []
+
+        # Add preamble
+        preamble_lines.each { |line| output << line }
+        output << "" unless preamble_lines.empty?
+
+        # Add blocks
+        blocks.each do |block|
+          # Add block header (no blank line before it)
+          header = block[:header]
+          if header && !header.strip.empty?
+            output << header.rstrip
+          end
+
+          # Add appraise call - using parentheses and curly braces format
+          name = block[:name]
+          output << "appraise(\"#{name}\") {"
+
+          # Add statements
+          statements = block[:statements] || extract_original_statements(block[:node])
+          statements.each do |stmt_info|
+            # Add any leading comments before this statement
+            leading = stmt_info[:leading_comments] || []
+            leading.each do |comment|
+              output << "  #{comment.slice.strip}"
+            end
+
+            node = stmt_info[:node]
+            # Normalize the statement to use parentheses
+            line = normalize_statement(node)
+
+            inline = stmt_info[:inline_comments] || []
+            inline_str = inline.map { |c| c.slice.strip }.join(" ")
+            output << "  #{line}#{" #{inline_str}" unless inline_str.empty?}"
+          end
+
+          output << "}"
+          output << ""
+        end
+
+        output.join("\n").strip + "\n"
+      end
+
+      def normalize_statement(node)
+        # Use PrismUtils for normalizing call nodes
+        return PrismUtils.node_to_source(node) unless node.is_a?(Prism::CallNode)
+        PrismUtils.normalize_call_node(node)
+      end
+
+      def normalize_argument(arg)
+        # Use PrismUtils for argument normalization
+        PrismUtils.normalize_argument(arg)
+      end
+
+      def extract_original_statements(node)
+        body = node.block&.body
+        return [] unless body
+
+        statements = body.is_a?(Prism::StatementsNode) ? body.body : [body]
+        statements.compact.map { |stmt| {node: stmt, inline_comments: [], leading_comments: []} }
+      end
+    end
+  end
+end

data/lib/kettle/dev/changelog_cli.rb

@@ -2,14 +2,27 @@
 
 module Kettle
   module Dev
+    # CLI for updating CHANGELOG.md with new version sections
+    #
+    # Automatically extracts unreleased changes, formats them into a new version section,
+    # includes coverage and YARD stats, and updates link references.
     class ChangelogCLI
       UNRELEASED_SECTION_HEADING = "[Unreleased]:"
+
+      # Initialize the changelog CLI
+      # Sets up paths for CHANGELOG.md and coverage.json
       def initialize
         @root = Kettle::Dev::CIHelpers.project_root
         @changelog_path = File.join(@root, "CHANGELOG.md")
         @coverage_path = File.join(@root, "coverage", "coverage.json")
       end
 
+      # Main entry point to update CHANGELOG.md
+      #
+      # Detects current version, extracts unreleased changes, formats them into
+      # a new version section with coverage/YARD stats, and updates all link references.
+      #
+      # @return [void]
       def run
         version = Kettle::Dev::Versioning.detect_version(@root)
         today = Time.now.strftime("%Y-%m-%d")