Add cycle validation helpers

Introduce validate_acyclic!/acyclic? with tests and document the new API
for checking untrusted trees.

Author: evolve75

API-CHANGES.md

@@ -15,6 +15,9 @@ smooth transition to the new APIs.
   now treat `nil` child slots as empty, preventing binary trees with missing
   children from reporting or yielding phantom siblings.
 
+* Added [Tree::TreeNode#validate_acyclic!][validate_acyclic] and
+  [Tree::TreeNode#acyclic?][acyclic] to detect cycles in untrusted trees.
+
 ## Release 2.2.0 Changes
 
 * [Tree::TreeNode#add][add] now raises `ArgumentError` when attempting to add
@@ -166,6 +169,7 @@ smooth transition to the new APIs.
 
 [access]: rdoc-ref:Tree::TreeNode#[]
 [add]: rdoc-ref:Tree::TreeNode#add
+[acyclic]: rdoc-ref:Tree::TreeNode#acyclic?
 [append]: rdoc-ref:Tree::TreeNode#<<
 [breadth_each]: rdoc-ref:Tree::TreeNode#breadth_each
 [btree_add]: rdoc-ref:Tree::BinaryTreeNode#add
@@ -192,3 +196,4 @@ smooth transition to the new APIs.
 [set_child_at]: rdoc-ref:Tree::BinaryTreeNode#set_child_at
 [siblings]: rdoc-ref:Tree::TreeNode#siblings
 [to_json]: rdoc-ref:Tree::Utils::JSONConverter#to_json
+[validate_acyclic]: rdoc-ref:Tree::TreeNode#validate_acyclic!

lib/tree.rb

@@ -199,6 +199,51 @@ def parentage
       parentage_array
     end
 
+    # @!attribute [r] acyclic?
+    # Returns +true+ if this (sub)tree has no cycles.
+    #
+    # @return [Boolean] +true+ if the (sub)tree is acyclic.
+    def acyclic?
+      validate_acyclic!
+      true
+    rescue ArgumentError
+      false
+    end
+
+    # Validates that the (sub)tree rooted at this node has no cycles.
+    #
+    # @raise [ArgumentError] Raised when a cycle is detected.
+    # @return [Tree::TreeNode] Returns +self+ when no cycle is found.
+    def validate_acyclic!
+      visited = {}
+      visiting = {}
+      stack = [[self, :enter]]
+
+      until stack.empty?
+        node, state = stack.pop
+        next unless node
+
+        if state == :exit
+          visiting.delete(node.object_id)
+          next
+        end
+
+        node_id = node.object_id
+        raise ArgumentError, 'Cycle detected in tree' if visiting.key?(node_id)
+        next if visited.key?(node_id)
+
+        visiting[node_id] = true
+        visited[node_id] = true
+
+        stack << [node, :exit]
+        node.children.reverse_each do |child|
+          stack << [child, :enter] if child
+        end
+      end
+
+      self
+    end
+
     # @!group Node Creation
 
     # Creates a new node with a name and optional content.

test/test_tree_structure.rb

@@ -416,5 +416,29 @@ def test_change_parent
       assert_equal('3', root2['3']['4'].parent.name)
       assert_nil(root1['2']['4'])
     end
+
+    def test_validate_acyclic
+      setup_test_tree
+
+      assert_equal(@root, @root.validate_acyclic!)
+      assert(@root.acyclic?, 'Expected the tree to be acyclic')
+    end
+
+    def test_validate_acyclic_detects_cycle
+      node_a = Tree::TreeNode.new('A')
+      node_b = Tree::TreeNode.new('B')
+
+      node_a.instance_variable_set(:@children, [node_b])
+      node_a.instance_variable_set(:@children_hash, { node_b.name => node_b })
+      node_b.instance_variable_set(:@parent, node_a)
+
+      node_b.instance_variable_set(:@children, [node_a])
+      node_b.instance_variable_set(:@children_hash, { node_a.name => node_a })
+      node_a.instance_variable_set(:@parent, node_b)
+
+      error = assert_raise(ArgumentError) { node_a.validate_acyclic! }
+      assert_match(/Cycle detected/, error.message)
+      assert_equal(false, node_a.acyclic?)
+    end
   end
 end