✨ max_recursion_depth control of recursion

pboling · pboling · commit ebe0b56cca78 · 2025-12-04T17:20:52.000-07:00
diff --git a/README.md b/README.md
@@ -298,6 +298,33 @@ merger = Prism::Merge::SmartMerger.new(
 # Result: Existing configs keep destination values, new configs added from template
 ```
 
+### Recursion Depth Limit
+
+Prism::Merge automatically detects when block bodies contain only literals or simple expressions (no mergeable statements) and treats them atomically. However, as a safety valve for edge cases, you can limit recursion depth:
+
+```ruby
+# Limit recursive merging to 3 levels deep
+merger = Prism::Merge::SmartMerger.new(
+  template,
+  destination,
+  max_recursion_depth: 3,
+)
+
+# Disable recursive merging entirely (treat all nodes atomically)
+merger = Prism::Merge::SmartMerger.new(
+  template,
+  destination,
+  max_recursion_depth: 0,
+)
+```
+
+**When to use:**
+
+- **`Float::INFINITY`** (default) - Normal operation, recursion terminates naturally based on content analysis.
+  - NOTE: If you get `stack level too deep (SystemStackError)`, please file a [bug](https://github.com/kettle-rb/prism-merge/issues)!
+- **Finite value** - Safety valve if you encounter edge cases with unexpected deep recursion
+- **`0`** - Disable recursive merging entirely; all matching nodes are treated atomically
+
 ### Custom Signature Generator
 
 By default, Prism::Merge uses intelligent structural signatures to match nodes. The signature determines how nodes are matched between template and destination files.
diff --git a/docs/Prism.html b/docs/Prism.html
@@ -142,7 +142,7 @@ <h5 class="example_title"><div class='inline'><p>With debug information</p>
 </div>
 
       <div id="footer">
-  Generated on Thu Dec  4 17:07:50 2025 by
+  Generated on Thu Dec  4 17:20:40 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.7).
 </div>
diff --git a/docs/Prism/Merge.html b/docs/Prism/Merge.html
@@ -158,7 +158,7 @@ <h2>
 </div>
 
       <div id="footer">
-  Generated on Thu Dec  4 17:07:50 2025 by
+  Generated on Thu Dec  4 17:20:40 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.7).
 </div>
diff --git a/docs/Prism/Merge/ConflictResolver.html b/docs/Prism/Merge/ConflictResolver.html
@@ -852,7 +852,7 @@ <h3 class="signature first" id="resolve-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Thu Dec  4 17:07:50 2025 by
+  Generated on Thu Dec  4 17:20:41 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.7).
 </div>
diff --git a/docs/Prism/Merge/DebugLogger.html b/docs/Prism/Merge/DebugLogger.html
@@ -322,7 +322,7 @@ <h3 class="signature first" id="debug-class_method">
 </div>
 
       <div id="footer">
-  Generated on Thu Dec  4 17:07:50 2025 by
+  Generated on Thu Dec  4 17:20:40 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.7).
 </div>
diff --git a/docs/Prism/Merge/DestinationParseError.html b/docs/Prism/Merge/DestinationParseError.html
@@ -175,7 +175,7 @@ <h2>Constructor Details</h2>
 </div>
 
       <div id="footer">
-  Generated on Thu Dec  4 17:07:50 2025 by
+  Generated on Thu Dec  4 17:20:40 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.7).
 </div>
diff --git a/docs/Prism/Merge/Error.html b/docs/Prism/Merge/Error.html
@@ -128,7 +128,7 @@ <h2>Direct Known Subclasses</h2>
 </div>
 
       <div id="footer">
-  Generated on Thu Dec  4 17:07:50 2025 by
+  Generated on Thu Dec  4 17:20:40 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.7).
 </div>
diff --git a/docs/Prism/Merge/FileAligner.html b/docs/Prism/Merge/FileAligner.html
@@ -633,7 +633,7 @@ <h3 class="signature first" id="align-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Thu Dec  4 17:07:50 2025 by
+  Generated on Thu Dec  4 17:20:40 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.7).
 </div>
diff --git a/docs/Prism/Merge/FileAligner/Anchor.html b/docs/Prism/Merge/FileAligner/Anchor.html
@@ -901,7 +901,7 @@ <h3 class="signature " id="template_range-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Thu Dec  4 17:07:50 2025 by
+  Generated on Thu Dec  4 17:20:41 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.7).
 </div>
diff --git a/docs/Prism/Merge/FileAligner/Boundary.html b/docs/Prism/Merge/FileAligner/Boundary.html
@@ -655,7 +655,7 @@ <h3 class="signature " id="template_lines-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Thu Dec  4 17:07:50 2025 by
+  Generated on Thu Dec  4 17:20:41 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.7).
 </div>
diff --git a/docs/Prism/Merge/FileAnalysis.html b/docs/Prism/Merge/FileAnalysis.html
@@ -1705,7 +1705,7 @@ <h3 class="signature " id="valid?-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Thu Dec  4 17:07:50 2025 by
+  Generated on Thu Dec  4 17:20:41 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.7).
 </div>
diff --git a/docs/Prism/Merge/FreezeNode.html b/docs/Prism/Merge/FreezeNode.html
@@ -1158,7 +1158,7 @@ <h3 class="signature " id="slice-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Thu Dec  4 17:07:50 2025 by
+  Generated on Thu Dec  4 17:20:40 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.7).
 </div>
diff --git a/docs/Prism/Merge/FreezeNode/InvalidStructureError.html b/docs/Prism/Merge/FreezeNode/InvalidStructureError.html
@@ -430,7 +430,7 @@ <h3 class="signature " id="unclosed_nodes-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Thu Dec  4 17:07:50 2025 by
+  Generated on Thu Dec  4 17:20:40 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.7).
 </div>
diff --git a/docs/Prism/Merge/FreezeNode/Location.html b/docs/Prism/Merge/FreezeNode/Location.html
@@ -397,7 +397,7 @@ <h3 class="signature first" id="cover?-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Thu Dec  4 17:07:50 2025 by
+  Generated on Thu Dec  4 17:20:40 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.7).
 </div>
diff --git a/docs/Prism/Merge/MergeResult.html b/docs/Prism/Merge/MergeResult.html
@@ -1368,7 +1368,7 @@ <h3 class="signature " id="to_s-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Thu Dec  4 17:07:50 2025 by
+  Generated on Thu Dec  4 17:20:41 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.7).
 </div>
diff --git a/docs/Prism/Merge/ParseError.html b/docs/Prism/Merge/ParseError.html
@@ -453,7 +453,7 @@ <h3 class="signature " id="parse_result-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Thu Dec  4 17:07:50 2025 by
+  Generated on Thu Dec  4 17:20:40 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.7).
 </div>
diff --git a/docs/Prism/Merge/SmartMerger.html b/docs/Prism/Merge/SmartMerger.html
@@ -1322,7 +1322,7 @@ <h5 class="example_title"><div class='inline'><p>Debug line provenance</p>
 </div>
 
       <div id="footer">
-  Generated on Thu Dec  4 17:07:50 2025 by
+  Generated on Thu Dec  4 17:20:41 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.7).
 </div>
diff --git a/docs/Prism/Merge/TemplateParseError.html b/docs/Prism/Merge/TemplateParseError.html
@@ -175,7 +175,7 @@ <h2>Constructor Details</h2>
 </div>
 
       <div id="footer">
-  Generated on Thu Dec  4 17:07:50 2025 by
+  Generated on Thu Dec  4 17:20:40 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.7).
 </div>
diff --git a/docs/Prism/Merge/Version.html b/docs/Prism/Merge/Version.html
@@ -131,7 +131,7 @@ <h2>
 </div>
 
       <div id="footer">
-  Generated on Thu Dec  4 17:07:50 2025 by
+  Generated on Thu Dec  4 17:20:40 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.7).
 </div>
diff --git a/docs/_index.html b/docs/_index.html
@@ -369,7 +369,7 @@ <h2>Namespace Listing A-Z</h2>
 </div>
 
       <div id="footer">
-  Generated on Thu Dec  4 17:07:50 2025 by
+  Generated on Thu Dec  4 17:20:40 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.7).
 </div>
diff --git a/docs/file.CHANGELOG.html b/docs/file.CHANGELOG.html
@@ -297,7 +297,7 @@ <h3 id="added-5">Added</h3>
 </div></div>
 
       <div id="footer">
-  Generated on Thu Dec  4 17:07:50 2025 by
+  Generated on Thu Dec  4 17:20:40 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.7).
 </div>
diff --git a/docs/file.CITATION.html b/docs/file.CITATION.html
@@ -82,7 +82,7 @@
 </div></div>
 
       <div id="footer">
-  Generated on Thu Dec  4 17:07:50 2025 by
+  Generated on Thu Dec  4 17:20:40 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.7).
 </div>
diff --git a/docs/file.CODE_OF_CONDUCT.html b/docs/file.CODE_OF_CONDUCT.html
@@ -191,7 +191,7 @@ <h2 id="attribution">Attribution</h2>
 </div></div>
 
       <div id="footer">
-  Generated on Thu Dec  4 17:07:50 2025 by
+  Generated on Thu Dec  4 17:20:40 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.7).
 </div>
diff --git a/docs/file.CONTRIBUTING.html b/docs/file.CONTRIBUTING.html
@@ -309,7 +309,7 @@ <h4 id="manual-process">Manual process</h4>
 </div></div>
 
       <div id="footer">
-  Generated on Thu Dec  4 17:07:50 2025 by
+  Generated on Thu Dec  4 17:20:40 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.7).
 </div>
diff --git a/docs/file.FUNDING.html b/docs/file.FUNDING.html
@@ -99,7 +99,7 @@ <h1 id="another-way-to-support-open-source-software">Another Way to Support Open
 </div></div>
 
       <div id="footer">
-  Generated on Thu Dec  4 17:07:50 2025 by
+  Generated on Thu Dec  4 17:20:40 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.7).
 </div>
diff --git a/docs/file.LICENSE.html b/docs/file.LICENSE.html
@@ -60,7 +60,7 @@
       <div id="content"><div id='filecontents'>The MIT License (MIT)<br><br>Copyright (c) 2025 Peter H. Boling<br><br>Permission is hereby granted, free of charge, to any person obtaining a copy<br>of this software and associated documentation files (the "Software"), to deal<br>in the Software without restriction, including without limitation the rights<br>to use, copy, modify, merge, publish, distribute, sublicense, and/or sell<br>copies of the Software, and to permit persons to whom the Software is<br>furnished to do so, subject to the following conditions:<br><br>The above copyright notice and this permission notice shall be included in<br>all copies or substantial portions of the Software.<br><br>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR<br>IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,<br>FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE<br>AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER<br>LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,<br>OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN<br>THE SOFTWARE.</div></div>
 
       <div id="footer">
-  Generated on Thu Dec  4 17:07:50 2025 by
+  Generated on Thu Dec  4 17:20:40 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.7).
 </div>
diff --git a/docs/file.README.html b/docs/file.README.html
@@ -515,6 +515,40 @@ <h3 id="combined-configuration">Combined Configuration</h3>
 # Result: Existing configs keep destination values, new configs added from template
 </code></pre>
 
+<h3 id="recursion-depth-limit">Recursion Depth Limit</h3>
+
+<p>Prism::Merge automatically detects when block bodies contain only literals or simple expressions (no mergeable statements) and treats them atomically. However, as a safety valve for edge cases, you can limit recursion depth:</p>
+
+<pre class="code language-ruby"><code class="language-ruby"># Limit recursive merging to 3 levels deep
+merger = Prism::Merge::SmartMerger.new(
+  template,
+  destination,
+  max_recursion_depth: 3,
+)
+
+# Disable recursive merging entirely (treat all nodes atomically)
+merger = Prism::Merge::SmartMerger.new(
+  template,
+  destination,
+  max_recursion_depth: 0,
+)
+</code></pre>
+
+<p><strong>When to use:</strong></p>
+
+<ul>
+  <li>
+<strong><code>Float::INFINITY</code></strong> (default) - Normal operation, recursion terminates naturally based on content analysis.
+    <ul>
+      <li>NOTE: If you get <code>stack level too deep (SystemStackError)</code>, please file a <a href="https://github.com/kettle-rb/prism-merge/issues">bug</a>!</li>
+    </ul>
+  </li>
+  <li>
+<strong>Finite value</strong> - Safety valve if you encounter edge cases with unexpected deep recursion</li>
+  <li>
+<strong><code>0</code></strong> - Disable recursive merging entirely; all matching nodes are treated atomically</li>
+</ul>
+
 <h3 id="custom-signature-generator">Custom Signature Generator</h3>
 
 <p>By default, Prism::Merge uses intelligent structural signatures to match nodes. The signature determines how nodes are matched between template and destination files.</p>
@@ -1334,7 +1368,7 @@ <h3 id="please-give-the-project-a-star--">Please give the project a star ⭐ ♥
 </div></div>
 
       <div id="footer">
-  Generated on Thu Dec  4 17:07:50 2025 by
+  Generated on Thu Dec  4 17:20:40 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.7).
 </div>
diff --git a/docs/file.REEK.html b/docs/file.REEK.html
@@ -61,7 +61,7 @@
 </div></div>
 
       <div id="footer">
-  Generated on Thu Dec  4 17:07:50 2025 by
+  Generated on Thu Dec  4 17:20:40 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.7).
 </div>
diff --git a/docs/file.RUBOCOP.html b/docs/file.RUBOCOP.html
@@ -161,7 +161,7 @@ <h2 id="benefits-of-rubocop_gradual">Benefits of rubocop_gradual</h2>
 </div></div>
 
       <div id="footer">
-  Generated on Thu Dec  4 17:07:50 2025 by
+  Generated on Thu Dec  4 17:20:40 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.7).
 </div>
diff --git a/docs/file.SECURITY.html b/docs/file.SECURITY.html
@@ -91,7 +91,7 @@ <h2 id="additional-support">Additional Support</h2>
 </div></div>
 
       <div id="footer">
-  Generated on Thu Dec  4 17:07:50 2025 by
+  Generated on Thu Dec  4 17:20:40 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.7).
 </div>
diff --git a/docs/file.merge.html b/docs/file.merge.html
@@ -416,7 +416,8 @@
 
   # Determine if two matching nodes should be recursively merged
   # Returns true for ClassNode, ModuleNode, SingletonClassNode, and CallNode/BeginNode
-  # with blocks that contain mergeable statements
+  # with blocks that contain mergeable statements.
+  # Returns false if max_recursion_depth has been reached (safety valve).
   def should_merge_recursively?: (untyped? template_node, untyped? dest_node) -&gt; bool
 
   # Check if a body (StatementsNode) contains statements that could be merged
@@ -440,7 +441,7 @@
 </div></div>
 
       <div id="footer">
-  Generated on Thu Dec  4 17:07:50 2025 by
+  Generated on Thu Dec  4 17:20:40 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.7).
 </div>
diff --git a/docs/index.html b/docs/index.html
diff --git a/docs/top-level-namespace.html b/docs/top-level-namespace.html
diff --git a/lib/prism/merge/smart_merger.rb b/lib/prism/merge/smart_merger.rb
diff --git a/sig/prism/merge.rbs b/sig/prism/merge.rbs
diff --git a/spec/prism/merge/smart_merger_spec.rb b/spec/prism/merge/smart_merger_spec.rb
