prism-merge 1.1.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: edeb460ce4645e2e6a8caf390cca9b23abeb88df9b3c314f6f86b42bc4ed68f5
-  data.tar.gz: 2f2fb56d28d1d8ddb2563b8b312186f06bd96b26bdf89753e1382724faac9332
+  metadata.gz: ae8f1b1cf1ae576917fae80dea44c38c181296c46f60f4dc70546d12ac0e6a90
+  data.tar.gz: 131295bf35a6da2038ea889f46ee9520f4a83a7daf9d983c2d0b91fb67644985
 SHA512:
-  metadata.gz: 1a5fa5900b24ba063df2de14c8772fda7b4dcebacfd2529dc41b465550b2baad3f8b8597d2c9759eac69b4025218843c35a41c14273c4ce69da294469b09b166
-  data.tar.gz: ac7e0ba8364617dcc2e9c67955b7c5cf303028c54cfaee272eb86a4f26378bd7c0eeed585db714b851bdbd42aae710b24a1fe9a6d629d880d0e26482e222cd9d
+  metadata.gz: 82dcffd3874394148696583ee3cddbb6cde3e33f4136ccd43dbae01213e8252999216320192be3af51fc3fd1662a4d7a524a44722254a19513de84d57efbf048
+  data.tar.gz: 49ab9213cb3ac2e2d691d3460983d18502c7ceef28a594b1c93578c8c3a8fc44c583472f4920aa9482058cd3815fed2365b75951cdf7e4c52b6c1d37150c3ec9

data/CHANGELOG.md

@@ -30,6 +30,44 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [1.1.1] - 2025-12-04
+
+- TAG: [v1.1.1][1.1.1t]
+- COVERAGE: 96.62% -- 857/887 lines in 9 files
+- BRANCH COVERAGE: 82.75% -- 331/400 branches in 9 files
+- 100.00% documented
+
+### Added
+
+- Documented comparison of this tool, git-merge, and IDE "Smart Merge" in README.md
+- Comprehensive node signature support for all Prism node types with nested content:
+  - `SingletonClassNode` - singleton class definitions (`class << self`)
+  - `CaseNode` / `CaseMatchNode` - case statements and pattern matching
+  - `WhileNode` / `UntilNode` / `ForNode` - loop constructs
+  - `BeginNode` - exception handling blocks
+  - `SuperNode` / `ForwardingSuperNode` - super calls with blocks
+  - `LambdaNode` - lambda expressions
+  - `PreExecutionNode` / `PostExecutionNode` - BEGIN/END blocks
+  - `ParenthesesNode` / `EmbeddedStatementsNode` - parenthesized expressions
+- Smart signature matching for assignment method calls (`config.setting = value`) now matches by receiver and method name, not by value, enabling proper merging of configuration blocks
+
+### Changed
+
+- Improved boundary ordering in merge timeline - destination-only content appearing after all template content now correctly appears at the end of merged output (was incorrectly appearing at the beginning)
+- Extended recursive merge support to handle `SingletonClassNode` and `BeginNode` in addition to existing `ClassNode`, `ModuleNode`, and `CallNode` types
+- **Freeze block validation expanded** - freeze blocks can now be placed inside more container node types:
+  - `SingletonClassNode` (`class << self ... end`)
+  - `DefNode` (method definitions)
+  - `LambdaNode` (lambda/proc definitions)
+  - `CallNode` with blocks (e.g., RSpec `describe`/`context` blocks)
+  - This allows protecting portions of method implementations or DSL block contents
+- Added README documentation comparing Prism::Merge algorithm to git merge and IDE smart merge strategies
+- Added RBS type definitions for `FreezeNode` class
+
+### Fixed
+
+- Documentation of freeze blocks, and configuration to customize the freeze token
+
 ## [1.1.0] - 2025-12-04
 
 - TAG: [v1.1.0][1.1.0t]
@@ -116,7 +154,9 @@ Please file a bug if you notice a violation of semantic versioning.
 
 - Initial release
 
-[Unreleased]: https://github.com/kettle-rb/prism-merge/compare/v1.1.0...HEAD
+[Unreleased]: https://github.com/kettle-rb/prism-merge/compare/v1.1.1...HEAD
+[1.1.1]: https://github.com/kettle-rb/prism-merge/compare/v1.1.0...v1.1.1
+[1.1.1t]: https://github.com/kettle-rb/prism-merge/releases/tag/v1.1.1
 [1.1.0]: https://github.com/kettle-rb/prism-merge/compare/v1.0.3...v1.1.0
 [1.1.0t]: https://github.com/kettle-rb/prism-merge/releases/tag/v1.1.0
 [1.0.3]: https://github.com/kettle-rb/prism-merge/compare/v1.0.2...v1.0.3

data/README.md

@@ -62,13 +62,14 @@ Prism::Merge is a standalone Ruby module that intelligently merges two versions
 - **Intelligent**: Matches nodes by structural signatures
 - **Recursive Merge**: Automatically merges class and module bodies recursively, intelligently combining nested methods and constants
 - **Comment-Preserving**: Comments are properly attached to relevant nodes and/or placement
-- **Freeze Block Support**: Respects `kettle-dev:freeze` markers for template merge control
+- **Freeze Block Support**: Respects freeze markers (default: `prism-merge:freeze` / `prism-merge:unfreeze`) for template merge control - customizable to match your project's conventions
 - **Full Provenance**: Tracks origin of every line
 - **Standalone**: No dependencies other than `prism` and `version_gem` (which is a tiny tool all my gems depend on)
 - **Customizable**:
   - `signature_generator` - callable custom signature generators
   - `signature_match_preference` - setting of `:template` or `:destination`
   - `add_template_only_nodes` - setting to retain nodes that do not exist in destination
+  - `freeze_token` - customize freeze block markers (default: `"prism-merge"`)
 
 ### Example
 
@@ -299,11 +300,42 @@ merger = Prism::Merge::SmartMerger.new(
 
 ### Custom Signature Generator
 
-By default, Prism::Merge uses intelligent structural signatures to match nodes:
-- **Conditionals** (`if`/`unless`) are matched by their condition only
-- **Assignments** (constants, variables) are matched by their name only
-- **Method calls** are matched by name and arguments (not block body)
-- **Other nodes** are matched by class and full source code
+By default, Prism::Merge uses intelligent structural signatures to match nodes. The signature determines how nodes are matched between template and destination files.
+
+#### Default Signature Matching
+
+| Node Type | Signature Format | Matching Behavior |
+|-----------|-----------------|-------------------|
+| `DefNode` | `[:def, name, params]` | Methods match by name and parameter names |
+| `ClassNode` | `[:class, name]` | Classes match by name |
+| `ModuleNode` | `[:module, name]` | Modules match by name |
+| `SingletonClassNode` | `[:singleton_class, expr]` | Singleton classes match by expression (`class << self`) |
+| `ConstantWriteNode` | `[:const, name]` | Constants match by name only (not value) |
+| `IfNode` / `UnlessNode` | `[:if, condition]` | Conditionals match by condition expression |
+| `CaseNode` | `[:case, predicate]` | Case statements match by the expression being switched |
+| `CaseMatchNode` | `[:case_match, predicate]` | Pattern matching cases match by expression |
+| `WhileNode` / `UntilNode` | `[:while, condition]` | Loops match by condition |
+| `ForNode` | `[:for, index, collection]` | For loops match by index variable and collection |
+| `BeginNode` | `[:begin, first_stmt]` | Begin blocks match by first statement (partial) |
+| `CallNode` (regular) | `[:call, name, first_arg]` | Method calls match by name and first argument |
+| `CallNode` (assignment) | `[:call, :method=, receiver]` | Assignment calls (`x.y = z`) match by receiver, not value |
+| `CallNode` (with block) | `[:call_with_block, name, first_arg]` | Block calls match by name and first argument |
+| `SuperNode` | `[:super, :with_block]` | Super calls match by presence of block |
+| `LambdaNode` | `[:lambda, params]` | Lambdas match by parameter signature |
+| `PreExecutionNode` | `[:pre_execution, line]` | BEGIN blocks match by line number |
+| `PostExecutionNode` | `[:post_execution, line]` | END blocks match by line number |
+
+#### Recursive Merge Support
+
+The following node types support **recursive body merging**, where nested content is intelligently combined:
+
+- `ClassNode` - class bodies are recursively merged
+- `ModuleNode` - module bodies are recursively merged
+- `SingletonClassNode` - singleton class bodies are recursively merged
+- `CallNode` with block - block bodies are recursively merged (e.g., `configure do ... end`)
+- `BeginNode` - begin/rescue/ensure blocks are recursively merged
+
+#### Custom Signature Generator
 
 You can provide a custom signature generator to control matching behavior:
 
@@ -336,17 +368,38 @@ merger = Prism::Merge::SmartMerger.new(
 
 ### Freeze Blocks
 
-Protect sections in the destination file from being overwritten by the template using freeze markers:
+Protect sections in the destination file from being overwritten by the template using freeze markers.
+
+By default, Prism::Merge uses `prism-merge` as the freeze token:
 
 ```ruby
 # In your destination.rb file
-# kettle-dev:freeze
+# prism-merge:freeze
 gem "custom-gem", path: "../custom"
 # Add any custom configuration you want to preserve
-# kettle-dev:unfreeze
+# prism-merge:unfreeze
+```
+
+You can customize the freeze token to match your project's conventions:
+
+```ruby
+# Use a custom freeze token (e.g., for kettle-dev projects)
+merger = Prism::Merge::SmartMerger.new(
+  template,
+  destination,
+  freeze_token: "kettle-dev",  # Now uses # kettle-dev:freeze / # kettle-dev:unfreeze
+)
 ```
 
-Freeze blocks are **always preserved** from the destination file during merge, regardless of template content.
+Freeze blocks are **always preserved** from the destination file during merge, regardless of template content. They can be placed inside:
+
+- Class and module bodies (`class Foo ... end`, `module Bar ... end`)
+- Singleton class bodies (`class << self ... end`)
+- Method definitions (`def method_name ... end`)
+- Lambda/proc bodies (`-> { ... }`)
+- Block-based DSLs (e.g., RSpec `describe`/`context` blocks)
+
+This allows you to protect entire methods, portions of method implementations, or sections within DSL blocks.
 
 ### Integration with Existing Systems
 
@@ -417,6 +470,53 @@ end
 # - custom_method is preserved (destination-only)
 ```
 
+### How Prism::Merge Compares to Other Merge Strategies
+
+Prism::Merge uses a **single-pass, AST-aware** algorithm that differs fundamentally from line-based merge tools like `git merge` and IDE smart merges:
+
+| Aspect | Git Merge (3-way) | IDE Smart Merge | Prism::Merge |
+|--------|-------------------|-----------------|--------------|
+| **Input** | 3 files (base, ours, theirs) | 2-3 files | 2 files (template, destination) |
+| **Unit of comparison** | Lines of text | Lines + some syntax awareness | AST nodes (Ruby structures) |
+| **Passes** | Multi-pass (LCS algorithm) | Multi-pass | Single-pass with anchors |
+| **Conflict handling** | Manual resolution with markers (`<<<<<<<`) | Interactive resolution | Automatic via signature matching |
+| **Language awareness** | None (text-only) | Basic (indentation, brackets) | Full Ruby AST understanding |
+| **Comment handling** | Treated as text | Treated as text | Attached to relevant nodes |
+| **Structural matching** | Line equality only | Line + heuristics | Node signatures (type + identifier) |
+| **Recursive merge** | No | Sometimes | Yes (class/module bodies) |
+| **Freeze blocks** | No | No | Yes (preserve destination sections) |
+
+#### Key Differences Explained
+
+**Git Merge (3-way merge):**
+- Requires a common ancestor (base) to detect changes from each side
+- Uses Longest Common Subsequence (LCS) algorithm in multiple passes
+- Produces conflict markers when both sides modify the same lines
+- Language-agnostic: treats Ruby, Python, and prose identically
+
+**IDE Smart Merge:**
+- Often uses 3-way merge as foundation
+- Adds heuristics for common patterns (moved blocks, reformatting)
+- May understand basic syntax for better conflict detection
+- Still fundamentally line-based with enhancements
+
+**Prism::Merge:**
+- Uses 2 files: template (source of truth) and destination (customized version)
+- Single-pass algorithm that builds a timeline of anchors (matches) and boundaries (differences)
+- Matches by **structural signature** (e.g., `[:def, :method_name]`), not line content
+- Automatically resolves conflicts based on configurable preference
+- Never produces conflict markers - always produces valid, runnable Ruby
+
+#### When to Use Each
+
+| Scenario | Best Tool |
+|----------|-----------|
+| Merging git branches with divergent changes | Git Merge |
+| Resolving complex conflicts interactively | IDE Smart Merge |
+| Updating project files from a template | **Prism::Merge** |
+| Maintaining customizations across template updates | **Prism::Merge** |
+| Merging non-Ruby files | Git Merge / IDE |
+
 ### With Debug Information
 
 Get detailed information about merge decisions:
@@ -486,12 +586,12 @@ Protect custom sections from template updates:
 ```ruby
 # destination.rb
 class MyApp
-  # kettle-dev:freeze
+  # prism-merge:freeze
   CUSTOM_CONFIG = {
     api_key: ENV.fetch("API_KEY"),
     endpoint: "https://custom.example.com",
   }
-  # kettle-dev:unfreeze
+  # prism-merge:unfreeze
 
   VERSION = "1.0.0"
 end
@@ -503,6 +603,18 @@ class MyApp
   VERSION = "2.0.0"
 end
 
+# Merge with default freeze token
+merger = Prism::Merge::SmartMerger.new(template, destination)
+result = merger.merge
+
+# Or use a custom freeze token if your project uses a different convention
+merger = Prism::Merge::SmartMerger.new(
+  template,
+  destination,
+  freeze_token: "kettle-dev",  # for kettle-dev projects
+)
+result = merger.merge
+
 # After merge, CUSTOM_CONFIG keeps destination values
 # but VERSION is updated to 2.0.0
 ```
@@ -596,9 +708,9 @@ RSpec.describe("Ruby file merging") do
     RUBY
 
     destination = <<~RUBY
-      # kettle-dev:freeze
+      # prism-merge:freeze
       CONFIG = { key: "secret" }
-      # kettle-dev:unfreeze
+      # prism-merge:unfreeze
     RUBY
 
     merger = Prism::Merge::SmartMerger.new(template, destination)
@@ -607,6 +719,28 @@ RSpec.describe("Ruby file merging") do
     # Freeze block content preserved
     expect(result).to(include('CONFIG = { key: "secret" }'))
   end
+
+  it "works with custom freeze tokens" do
+    template = <<~RUBY
+      CONFIG = {}
+    RUBY
+
+    destination = <<~RUBY
+      # my-app:freeze
+      CONFIG = { key: "secret" }
+      # my-app:unfreeze
+    RUBY
+
+    merger = Prism::Merge::SmartMerger.new(
+      template,
+      destination,
+      freeze_token: "my-app",  # Match your project's freeze token
+    )
+    result = merger.merge
+
+    # Freeze block content preserved
+    expect(result).to(include('CONFIG = { key: "secret" }'))
+  end
 end
 ```
 
@@ -973,7 +1107,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-0.805-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-0.887-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/lib/prism/merge/file_analysis.rb

@@ -322,15 +322,118 @@ module Prism
         end
       end
 
-      # Generate default signature for a node
+      # Generate default structural signature for a Prism node.
+      #
+      # Signatures are used to match nodes between template and destination files.
+      # Nodes with identical signatures are considered "the same" for merge purposes.
+      #
       # @param node [Prism::Node] Node to generate signature for
-      # @return [Array] Signature array [type, name, params, ...]
+      # @return [Array] Signature array with format [:type, identifier, ...]
+      #
+      # @note Supported node types and their signature formats:
+      #
+      #   **Method/Class Definitions:**
+      #   - `DefNode` → `[:def, name, [param_names]]`
+      #   - `ClassNode` → `[:class, constant_path]`
+      #   - `ModuleNode` → `[:module, constant_path]`
+      #   - `SingletonClassNode` → `[:singleton_class, expression]`
+      #
+      #   **Constants:**
+      #   - `ConstantWriteNode` → `[:const, name]`
+      #   - `ConstantPathWriteNode` → `[:const, target]`
+      #
+      #   **Conditionals:**
+      #   - `IfNode` → `[:if, condition_source]`
+      #   - `UnlessNode` → `[:unless, condition_source]`
+      #
+      #   **Case Statements:**
+      #   - `CaseNode` → `[:case, predicate]`
+      #   - `CaseMatchNode` → `[:case_match, predicate]`
+      #
+      #   **Loops:**
+      #   - `WhileNode` → `[:while, condition]`
+      #   - `UntilNode` → `[:until, condition]`
+      #   - `ForNode` → `[:for, index, collection]`
+      #
+      #   **Exception Handling:**
+      #   - `BeginNode` → `[:begin, first_statement_preview]`
+      #
+      #   **Method Calls:**
+      #   - `CallNode` (regular) → `[:call, method_name, first_arg]`
+      #   - `CallNode` (assignment, e.g., `x.y = z`) → `[:call, :method=, receiver]`
+      #   - `CallNode` (with block) → `[:call_with_block, method_name, first_arg_or_receiver]`
+      #
+      #   **Super Calls:**
+      #   - `SuperNode` → `[:super, :with_block | :no_block]`
+      #   - `ForwardingSuperNode` → `[:forwarding_super, :with_block | :no_block]`
+      #
+      #   **Lambdas:**
+      #   - `LambdaNode` → `[:lambda, parameters_source]`
+      #
+      #   **Special Blocks:**
+      #   - `PreExecutionNode` → `[:pre_execution, line_number]`
+      #   - `PostExecutionNode` → `[:post_execution, line_number]`
+      #
+      #   **Other:**
+      #   - `ParenthesesNode` → `[:parens, first_expression_preview]`
+      #   - `EmbeddedStatementsNode` → `[:embedded, statements_source]`
+      #   - `FreezeNode` → Uses FreezeNode#signature
+      #   - Unknown nodes → `[:other, class_name, line_number]`
+      #
+      # @example Method definition signature
+      #   # def greet(name, greeting: "Hello")
+      #   compute_node_signature(def_node)
+      #   # => [:def, :greet, [:name, :greeting]]
+      #
+      # @example Assignment method call signature
+      #   # config.setting = "value"
+      #   compute_node_signature(call_node)
+      #   # => [:call, :setting=, "config"]
+      #
+      # @example Block method call signature
+      #   # appraise "ruby-3.3" do ... end
+      #   compute_node_signature(call_node)
+      #   # => [:call_with_block, :appraise, "ruby-3.3"]
+      #
+      # @api private
       def compute_node_signature(node)
         # IMPORTANT: Do NOT call node.signature - Prism nodes have their own signature method
         # that returns [node_type_symbol, source_text] which is not what we want for matching.
         # We need our own signature format: [:type_symbol, identifier, params]
+        #
+        # Node types with nested content (from Prism) that we may encounter:
+        # - BeginNode: statements, rescue_clause, else_clause, ensure_clause
+        # - BlockNode: body (handled via parent CallNode)
+        # - CallNode: block
+        # - CaseMatchNode: else_clause, conditions, consequent
+        # - CaseNode: else_clause, conditions, consequent
+        # - ClassNode: body
+        # - DefNode: body
+        # - ElseNode: statements (handled via parent)
+        # - EmbeddedStatementsNode: statements
+        # - EnsureNode: statements (handled via parent BeginNode)
+        # - ForNode: statements
+        # - ForwardingSuperNode: block
+        # - IfNode: statements, consequent
+        # - InNode: statements (handled via parent CaseMatchNode)
+        # - IndexAndWriteNode, IndexOperatorWriteNode, IndexOrWriteNode: block
+        # - LambdaNode: body
+        # - ModuleNode: body
+        # - ParenthesesNode: body
+        # - PostExecutionNode: statements (END { })
+        # - PreExecutionNode: statements (BEGIN { })
+        # - ProgramNode: statements (top-level)
+        # - RescueNode: statements, consequent (handled via parent BeginNode)
+        # - SingletonClassNode: body
+        # - StatementsNode: body
+        # - SuperNode: block
+        # - UnlessNode: statements, else_clause, consequent
+        # - UntilNode: statements
+        # - WhenNode: statements, conditions (handled via parent CaseNode)
+        # - WhileNode: statements
 
         case node
+        # === Method definitions ===
         when Prism::DefNode
           # Extract parameter names from ParametersNode
           params = if node.parameters
@@ -347,23 +450,150 @@ module Prism
             []
           end
           [:def, node.name, params]
+
+        # === Class/Module definitions ===
         when Prism::ClassNode
           [:class, node.constant_path.slice]
         when Prism::ModuleNode
           [:module, node.constant_path.slice]
+        when Prism::SingletonClassNode
+          # class << self or class << expr
+          expr = begin
+            node.expression.slice
+          rescue
+            "self"
+          end
+          [:singleton_class, expr]
+
+        # === Constants ===
         when Prism::ConstantWriteNode, Prism::ConstantPathWriteNode
           [:const, node.name || node.target.slice]
+
+        # === Conditionals ===
         when Prism::IfNode, Prism::UnlessNode
           # Conditionals match by their condition expression
           condition_source = node.predicate.slice
           [node.is_a?(Prism::IfNode) ? :if : :unless, condition_source]
+
+        # === Case/Switch statements ===
+        when Prism::CaseNode
+          # case expr; when ... end - match by the expression being switched on
+          predicate = node.predicate&.slice || ""
+          [:case, predicate]
+        when Prism::CaseMatchNode
+          # case expr; in ... end (pattern matching) - match by the expression
+          predicate = node.predicate&.slice || ""
+          [:case_match, predicate]
+
+        # === Loops ===
+        when Prism::WhileNode
+          [:while, node.predicate.slice]
+        when Prism::UntilNode
+          [:until, node.predicate.slice]
+        when Prism::ForNode
+          # for i in collection - match by index and collection
+          index = node.index.slice
+          collection = node.collection.slice
+          [:for, index, collection]
+
+        # === Exception handling ===
+        when Prism::BeginNode
+          # begin/rescue/ensure blocks - unique by position within parent
+          # Since these don't have a natural identifier, use first statement
+          first_stmt = node.statements&.body&.first&.slice&.[](0, 30) || ""
+          [:begin, first_stmt]
+
+        # === Method calls ===
+        when Prism::CallNode
+          # Method calls match by name and context
+          # For assignment methods (ending in =), match by receiver + method name only
+          # For other calls, include first argument as identifier (e.g., appraise "name")
+          method_name = node.name.to_s
+          receiver = node.receiver&.slice
+
+          if method_name.end_with?("=")
+            # Assignment method: config.setting = "value"
+            # Match by receiver and method name, NOT the value being assigned
+            if node.block
+              [:call_with_block, node.name, receiver]
+            else
+              [:call, node.name, receiver]
+            end
+          else
+            # Regular method call: appraise "unlocked" do ... end
+            # Match by method name and first argument (which identifies the call)
+            first_arg = extract_first_argument_value(node)
+            if node.block
+              [:call_with_block, node.name, first_arg]
+            else
+              [:call, node.name, first_arg]
+            end
+          end
+
+        # === Super calls ===
+        when Prism::SuperNode
+          [:super, node.block ? :with_block : :no_block]
+        when Prism::ForwardingSuperNode
+          [:forwarding_super, node.block ? :with_block : :no_block]
+
+        # === Lambdas ===
+        when Prism::LambdaNode
+          # Lambdas don't have names, but we can identify by parameter signature
+          params = if node.parameters
+            node.parameters.slice
+          else
+            ""
+          end
+          [:lambda, params]
+
+        # === Special blocks ===
+        when Prism::PreExecutionNode
+          # BEGIN { } blocks
+          [:pre_execution, node.location.start_line]
+        when Prism::PostExecutionNode
+          # END { } blocks
+          [:post_execution, node.location.start_line]
+
+        # === Parenthesized expressions ===
+        when Prism::ParenthesesNode
+          # Usually transparent, but if it appears at top level, identify by content
+          first_expr = node.body&.body&.first&.slice&.[](0, 30) || ""
+          [:parens, first_expr]
+
+        # === Embedded statements (string interpolation) ===
+        when Prism::EmbeddedStatementsNode
+          [:embedded, node.statements&.slice || ""]
+
+        # === FreezeNode (our custom wrapper) ===
         when FreezeNode
           # FreezeNode has its own signature method with normalized content
           node.signature
+
         else
+          # Fallback: use class name and line number
+          # Nodes that reach here may not merge well across files
           [:other, node.class.name, node.location.start_line]
         end
       end
+
+      # Extract the value of the first argument from a CallNode for signature matching.
+      # Returns the unescaped string value for StringNode, or the slice for other node types.
+      #
+      # @param node [Prism::CallNode] The call node to extract argument from
+      # @return [String, nil] The first argument value, or nil if no arguments
+      def extract_first_argument_value(node)
+        return unless node.arguments&.arguments&.any?
+
+        first_arg = node.arguments.arguments.first
+        case first_arg
+        when Prism::StringNode
+          first_arg.unescaped
+        when Prism::SymbolNode
+          first_arg.unescaped.to_sym
+        else
+          first_arg.slice
+        end
+      end
     end
   end
 end

data/lib/prism/merge/freeze_node.rb

@@ -118,17 +118,28 @@ module Prism
           fully_contained = node_start >= @start_line && node_end <= @end_line
 
           # Check if node completely encompasses the freeze block
-          # This is only valid for ClassNode/ModuleNode (freeze blocks at class/module body level)
-          # For other nodes (methods, etc.), this is invalid
+          # This is valid for nodes that define a body scope where freeze blocks make sense:
+          # - ClassNode, ModuleNode, SingletonClassNode (class/module definitions)
+          # - CallNode with blocks (like RSpec describe/context blocks)
+          # - DefNode (method definitions)
+          # - LambdaNode (lambda/proc definitions)
           encompasses = node_start < @start_line && node_end > @end_line
-          valid_encompass = encompasses && (node.is_a?(Prism::ClassNode) || node.is_a?(Prism::ModuleNode))
+          valid_encompass = encompasses && (
+            node.is_a?(Prism::ClassNode) ||
+            node.is_a?(Prism::ModuleNode) ||
+            node.is_a?(Prism::SingletonClassNode) ||
+            node.is_a?(Prism::DefNode) ||
+            node.is_a?(Prism::LambdaNode) ||
+            (node.is_a?(Prism::CallNode) && node.block) ||
+            (node.is_a?(Prism::LocalVariableWriteNode) && node.value.is_a?(Prism::LambdaNode))
+          )
 
           # Check if node partially overlaps (invalid - unclosed/incomplete structure)
           partially_overlaps = !fully_contained && !encompasses &&
             ((node_start < @start_line && node_end >= @start_line) ||
              (node_start <= @end_line && node_end > @end_line))
 
-          # Invalid if: partial overlap OR if a non-class/module node encompasses the freeze block
+          # Invalid if: partial overlap OR if an unsupported node type encompasses the freeze block
           if partially_overlaps || (encompasses && !valid_encompass)
             unclosed << node
           end

data/lib/prism/merge/smart_merger.rb

@@ -270,9 +270,25 @@ module Prism
         end
 
         boundaries.each do |boundary|
-          # Sort boundaries by their starting position
-          t_start = boundary.template_range&.begin || 0
-          d_start = boundary.dest_range&.begin || 0
+          # Sort boundaries by their position relative to anchors
+          # - Boundaries before first anchor: use their position (or 0 if no template range)
+          # - Boundaries between anchors: use template position
+          # - Boundaries after last anchor: use Float::INFINITY to place at end
+
+          if boundary.prev_anchor.nil? && boundary.next_anchor
+            # Before first anchor - place at beginning
+            t_start = boundary.template_range&.begin || 0
+            d_start = boundary.dest_range&.begin || 0
+          elsif boundary.prev_anchor && boundary.next_anchor.nil?
+            # After last anchor - place at end
+            t_start = Float::INFINITY
+            d_start = boundary.dest_range&.begin || Float::INFINITY
+          else
+            # Between anchors or no anchors at all
+            t_start = boundary.template_range&.begin || boundary.prev_anchor&.template_end&.+(1) || 0
+            d_start = boundary.dest_range&.begin || 0
+          end
+
           sort_key = [t_start, d_start, 1] # 1 ensures boundaries come after anchors at same position
 
           timeline << {type: :boundary, boundary: boundary, sort_key: sort_key}
@@ -386,9 +402,10 @@ module Prism
 
       # Determines if two matching nodes should be recursively merged.
       #
-      # Recursive merge is performed for matching class/module definitions to intelligently
-      # combine their body contents (nested methods, constants, etc.). This allows template
-      # updates to class internals to be merged with destination customizations.
+      # Recursive merge is performed for matching class/module definitions and
+      # CallNodes with blocks to intelligently combine their body contents
+      # (nested methods, constants, etc.). This allows template updates to
+      # internals to be merged with destination customizations.
       #
       # @param template_node [Prism::Node, nil] Node from template file
       # @param dest_node [Prism::Node, nil] Node from destination file
@@ -396,15 +413,40 @@ module Prism
       #
       # @note Recursive merge is NOT performed for:
       #   - Conditional nodes (if/unless) - treated as atomic units
-      #   - Classes/modules containing freeze blocks - frozen content would be lost
+      #   - Classes/modules/blocks containing freeze blocks - frozen content would be lost
       #   - Nodes of different types
       def should_merge_recursively?(template_node, dest_node)
         return false unless template_node && dest_node
 
-        is_class_or_module = (template_node.is_a?(Prism::ClassNode) && dest_node.is_a?(Prism::ClassNode)) ||
-          (template_node.is_a?(Prism::ModuleNode) && dest_node.is_a?(Prism::ModuleNode))
+        # Both nodes must be the same type
+        return false unless template_node.class == dest_node.class
+
+        # Determine if this node type supports recursive merging
+        can_merge_recursively = case template_node
+        when Prism::ClassNode, Prism::ModuleNode, Prism::SingletonClassNode
+          # Class/module definitions - merge their body contents
+          true
+        when Prism::CallNode
+          # Only merge if both have blocks
+          template_node.block && dest_node.block
+        when Prism::BeginNode
+          # begin/rescue/ensure blocks - merge statements
+          template_node.statements && dest_node.statements
+        when Prism::CaseNode, Prism::CaseMatchNode
+          # Case statements could potentially merge conditions, but this is complex
+          # For now, treat as atomic unless both have same structure
+          false
+        when Prism::WhileNode, Prism::UntilNode, Prism::ForNode
+          # Loops - could merge body, but usually should be atomic
+          false
+        when Prism::LambdaNode
+          # Lambdas - could merge body, but typically atomic
+          false
+        else
+          false
+        end
 
-        return false unless is_class_or_module
+        return false unless can_merge_recursively
 
         # Don't recursively merge if either node contains freeze blocks
         # (they would be lost in the nested merge since we pass freeze_token: nil)
@@ -421,7 +463,26 @@ module Prism
       # @api private
       def node_contains_freeze_blocks?(node)
         return false unless @freeze_token
-        return false unless node.body
+
+        # Check if node has nested content that could contain freeze blocks
+        # Different node types store content in different attributes
+        has_content = case node
+        when Prism::ClassNode, Prism::ModuleNode, Prism::SingletonClassNode,
+             Prism::LambdaNode, Prism::ParenthesesNode
+          node.body
+        when Prism::IfNode, Prism::UnlessNode, Prism::WhileNode, Prism::UntilNode,
+             Prism::ForNode, Prism::BeginNode
+          node.statements
+        when Prism::CallNode, Prism::SuperNode, Prism::ForwardingSuperNode
+          node.block
+        else
+          # Fallback for any other nodes
+          node.respond_to?(:body) && node.body ||
+            node.respond_to?(:statements) && node.statements ||
+            node.respond_to?(:block) && node.block
+        end
+
+        return false unless has_content
 
         # Check if any comments in the node's range contain freeze markers
         freeze_pattern = /#\s*#{Regexp.escape(@freeze_token)}:(freeze|unfreeze)/i
@@ -438,14 +499,14 @@ module Prism
         end
       end
 
-      # Recursively merges the body of matching class or module nodes.
+      # Recursively merges the body of matching class, module, or call-with-block nodes.
       #
-      # This method extracts the body content (everything between the class/module
+      # This method extracts the body content (everything between the opening
       # declaration and the closing 'end'), creates a new nested SmartMerger to merge
-      # those bodies, and then reassembles the complete class/module with the merged body.
+      # those bodies, and then reassembles the complete node with the merged body.
       #
-      # @param template_node [Prism::ClassNode, Prism::ModuleNode] Class/module from template
-      # @param dest_node [Prism::ClassNode, Prism::ModuleNode] Class/module from destination
+      # @param template_node [Prism::ClassNode, Prism::ModuleNode, Prism::CallNode] Node from template
+      # @param dest_node [Prism::ClassNode, Prism::ModuleNode, Prism::CallNode] Node from destination
       # @param anchor [FileAligner::Anchor] The anchor representing this match
       #
       # @note The nested merger is configured with:
@@ -469,23 +530,39 @@ module Prism
         )
         merged_body = body_merger.merge.rstrip
 
-        # Add the opening line (class/module declaration) with leading comments
-        source_analysis = (@signature_match_preference == :template) ? @template_analysis : @dest_analysis
-        source_node = (@signature_match_preference == :template) ? template_node : dest_node
-        source_anchor_start = (@signature_match_preference == :template) ? anchor.template_start : anchor.dest_start
+        # Determine leading comments handling:
+        # - If template has leading comments, use template's based on signature_match_preference
+        # - If template has NO leading comments but destination does, preserve destination's
+        template_has_leading = anchor.template_start < template_node.location.start_line
+        dest_has_leading = anchor.dest_start < dest_node.location.start_line
 
-        # Add leading comments
-        (source_anchor_start...source_node.location.start_line).each do |line_num|
-          line = source_analysis.line_at(line_num)
-          @result.add_line(
-            line.chomp,
-            decision: MergeResult::DECISION_REPLACED,
-            template_line: ((@signature_match_preference == :template) ? line_num : nil),
-            dest_line: ((@signature_match_preference == :destination) ? line_num : nil),
-          )
+        if template_has_leading && @signature_match_preference == :template
+          # Use template's leading comments
+          (anchor.template_start...template_node.location.start_line).each do |line_num|
+            line = @template_analysis.line_at(line_num)
+            @result.add_line(
+              line.chomp,
+              decision: MergeResult::DECISION_REPLACED,
+              template_line: line_num,
+            )
+          end
+        elsif dest_has_leading
+          # Preserve destination's leading comments (either because preference is :destination,
+          # or because template has none)
+          (anchor.dest_start...dest_node.location.start_line).each do |line_num|
+            line = @dest_analysis.line_at(line_num)
+            @result.add_line(
+              line.chomp,
+              decision: MergeResult::DECISION_KEPT_DEST,
+              dest_line: line_num,
+            )
+          end
         end
 
-        # Add the class/module opening line
+        # Add the opening line (based on signature_match_preference)
+        source_analysis = (@signature_match_preference == :template) ? @template_analysis : @dest_analysis
+        source_node = (@signature_match_preference == :template) ? template_node : dest_node
+
         opening_line = source_analysis.line_at(source_node.location.start_line)
         @result.add_line(
           opening_line.chomp,
@@ -526,14 +603,40 @@ module Prism
       # @note Handles different node types:
       #   - ClassNode/ModuleNode: Uses node.body (StatementsNode)
       #   - IfNode/UnlessNode: Uses node.statements (StatementsNode)
+      #   - CallNode with block: Uses node.block.body (StatementsNode)
       #
       # @api private
       def extract_node_body(node, analysis)
         # Get the statements node based on node type
-        statements_node = if node.is_a?(Prism::ClassNode) || node.is_a?(Prism::ModuleNode)
+        # Different node types store their body/statements in different attributes
+        statements_node = case node
+        when Prism::ClassNode, Prism::ModuleNode, Prism::SingletonClassNode, Prism::LambdaNode
+          # These use .body which returns a StatementsNode
           node.body
-        elsif node.is_a?(Prism::IfNode) || node.is_a?(Prism::UnlessNode)
+        when Prism::IfNode, Prism::UnlessNode, Prism::WhileNode, Prism::UntilNode, Prism::ForNode
+          # These use .statements
           node.statements
+        when Prism::CallNode
+          # CallNode stores body inside block.body
+          node.block&.body
+        when Prism::BeginNode
+          # BeginNode uses .statements for the main body
+          node.statements
+        when Prism::CaseNode, Prism::CaseMatchNode
+          # Case nodes have conditions (WhenNode/InNode array), not a simple body
+          # Return nil for now - these need special handling
+          nil
+        when Prism::ParenthesesNode
+          node.body
+        else
+          # Try common patterns
+          if node.respond_to?(:body)
+            node.body
+          elsif node.respond_to?(:statements)
+            node.statements
+          elsif node.respond_to?(:block) && node.block
+            node.block.body
+          end
         end
 
         return "" unless statements_node&.is_a?(Prism::StatementsNode)

data/lib/prism/merge/version.rb

@@ -5,7 +5,7 @@ module Prism
     # Version information for Prism::Merge
     module Version
       # Current version of the prism-merge gem
-      VERSION = "1.1.0"
+      VERSION = "1.1.1"
     end
     VERSION = Version::VERSION # traditional location
   end

data/sig/prism/merge.rbs

@@ -22,6 +22,64 @@ module Prism
     class DestinationParseError < ParseError
     end
 
+    # Wrapper to represent freeze blocks as first-class nodes.
+    # Freeze blocks can be placed inside:
+    # - ClassNode, ModuleNode, SingletonClassNode (class/module definitions)
+    # - DefNode (method definitions)
+    # - LambdaNode (lambda/proc definitions)
+    # - CallNode with blocks (e.g., RSpec describe/context blocks)
+    class FreezeNode
+      class InvalidStructureError < StandardError
+        attr_reader start_line: Integer?
+        attr_reader end_line: Integer?
+        attr_reader unclosed_nodes: Array[untyped]
+
+        def initialize: (String message, ?start_line: Integer?, ?end_line: Integer?, ?unclosed_nodes: Array[untyped]) -> void
+      end
+
+      class Location
+        attr_reader start_line: Integer
+        attr_reader end_line: Integer
+
+        def initialize: (Integer start_line, Integer end_line) -> void
+      end
+
+      attr_reader start_line: Integer
+      attr_reader end_line: Integer
+      attr_reader content: String
+      attr_reader nodes: Array[untyped]
+      attr_reader start_marker: String?
+      attr_reader end_marker: String?
+
+      def initialize: (
+        start_line: Integer,
+        end_line: Integer,
+        analysis: FileAnalysis,
+        ?nodes: Array[untyped],
+        ?overlapping_nodes: Array[untyped]?,
+        ?start_marker: String?,
+        ?end_marker: String?
+      ) -> void
+
+      def location: () -> Location
+
+      def signature: () -> Array[Symbol | Integer]
+
+      def line_range: () -> Range[Integer]
+
+      def contains_line?: (Integer line_num) -> bool
+
+      def overlaps?: (untyped other) -> bool
+
+      def to_s: () -> String
+
+      def inspect: () -> String
+
+      private
+
+      def validate_structure!: () -> void
+    end
+
     class FileAnalysis
       FREEZE_START: Regexp
       FREEZE_END: Regexp
@@ -92,6 +150,33 @@ module Prism
       def build_comment_map: () -> Hash[Integer, Array[untyped]]
 
       def default_signature: (untyped node) -> Array[untyped]
+
+      # Compute structural signature for node matching
+      # Returns signature arrays like:
+      #   [:def, Symbol, Array[Symbol]]           - method definitions
+      #   [:class, String]                        - class definitions
+      #   [:module, String]                       - module definitions
+      #   [:singleton_class, String]              - singleton class definitions
+      #   [:const, Symbol | String]               - constant assignments
+      #   [:if, String] | [:unless, String]       - conditionals
+      #   [:case, String] | [:case_match, String] - case statements
+      #   [:while, String] | [:until, String]     - while/until loops
+      #   [:for, String, String]                  - for loops
+      #   [:begin, String]                        - begin blocks
+      #   [:call, Symbol, String?]                - method calls
+      #   [:call_with_block, Symbol, String?]     - method calls with blocks
+      #   [:super, Symbol]                        - super calls
+      #   [:forwarding_super, Symbol]             - forwarding super calls
+      #   [:lambda, String]                       - lambda expressions
+      #   [:pre_execution, Integer]               - BEGIN blocks
+      #   [:post_execution, Integer]              - END blocks
+      #   [:parens, String]                       - parenthesized expressions
+      #   [:embedded, String]                     - embedded statements
+      #   [:other, String, Integer]               - fallback for unknown nodes
+      def compute_node_signature: (untyped node) -> Array[untyped]
+
+      # Extract first argument value from a CallNode
+      def extract_first_argument_value: (untyped node) -> (String | Symbol | nil)
     end
 
     class FileAligner
@@ -260,6 +345,25 @@ module Prism
       def add_exact_match_from_template: (FileAligner::Anchor anchor) -> void
 
       def process_boundary: (FileAligner::Boundary boundary) -> void
+
+      # Find a node that overlaps with a line range
+      def find_node_in_range: (FileAnalysis analysis, Integer start_line, Integer end_line) -> untyped?
+
+      # Find a node at a specific line (deprecated)
+      def find_node_at_line: (FileAnalysis analysis, Integer line_num) -> untyped?
+
+      # Determine if two matching nodes should be recursively merged
+      # Returns true for ClassNode, ModuleNode, SingletonClassNode, CallNode with blocks, BeginNode
+      def should_merge_recursively?: (untyped? template_node, untyped? dest_node) -> bool
+
+      # Check if a node's body contains freeze block markers
+      def node_contains_freeze_blocks?: (untyped node) -> bool
+
+      # Recursively merge the body of matching class, module, or call-with-block nodes
+      def merge_node_body_recursively: (untyped template_node, untyped dest_node, FileAligner::Anchor anchor) -> void
+
+      # Extract the body content of a node (without declaration and closing 'end')
+      def extract_node_body: (untyped node, FileAnalysis analysis) -> String
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: prism-merge
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.1.1
 platform: ruby
 authors:
 - Peter H. Boling
@@ -265,10 +265,10 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://prism-merge.galtzo.com/
-  source_code_uri: https://github.com/kettle-rb/prism-merge/tree/v1.1.0
-  changelog_uri: https://github.com/kettle-rb/prism-merge/blob/v1.1.0/CHANGELOG.md
+  source_code_uri: https://github.com/kettle-rb/prism-merge/tree/v1.1.1
+  changelog_uri: https://github.com/kettle-rb/prism-merge/blob/v1.1.1/CHANGELOG.md
   bug_tracker_uri: https://github.com/kettle-rb/prism-merge/issues
-  documentation_uri: https://www.rubydoc.info/gems/prism-merge/1.1.0
+  documentation_uri: https://www.rubydoc.info/gems/prism-merge/1.1.1
   funding_uri: https://github.com/sponsors/pboling
   wiki_uri: https://github.com/kettle-rb/prism-merge/wiki
   news_uri: https://www.railsbling.com/tags/prism-merge