Enforce baseline checks in fast mode (#45)

Keep nil-child and duplicate-name guards always on, document the risk with
benchmark guidance, and expand checks-disabled coverage.

Author: evolve75

API-CHANGES.md

@@ -31,10 +31,12 @@ smooth transition to the new APIs.
   (see #104).
 
 * Added per-tree validation toggles via `checks: false` on `Tree::TreeNode.new`
-  to allow disabling guard checks in performance-critical code paths. This is
-  potentially dangerous and can lead to unexpected behavior if invalid data
-  enters the tree. Only disable checks with clear performance benchmark data
-  supporting the risk (see #45).
+  to allow disabling guard checks in performance-critical code paths. Some
+  baseline guards (nil child checks, duplicate child name checks) are always
+  enforced to avoid corrupting the tree. Disabling checks is still potentially
+  dangerous and can lead to unexpected behavior if invalid data enters the tree.
+  Only disable checks with clear performance benchmark data supporting the risk
+  (see #45).
 
 ## Release 2.2.0 Changes
 

History.md

@@ -23,9 +23,10 @@
   `HashWithIndifferentAccess` data (see #104).
 
 * Add a per-tree `checks: false` option to skip validation checks when
-  performance matters. This is risky and can yield unexpected behavior if
-  invalid data is introduced. Only disable checks with benchmark data that
-  justifies the risk (see #45).
+  performance matters. Some baseline guards (nil children, duplicate child
+  names) are always enforced to avoid corrupting the tree. This is still risky
+  and can yield unexpected behavior if invalid data is introduced. Only
+  disable checks with benchmark data that justifies the risk (see #45).
 
 ### 2.2.1pre / 2026-02-07
 

lib/tree.rb

@@ -256,10 +256,11 @@ def validate_acyclic!
     #
     # @param [Object] content Content of the node.
     # @param [Hash, nil] options Optional settings such as { checks: false } to
-    #   disable validation checks for performance-critical usage. Disabling
-    #   checks is risky and can lead to unexpected behavior if invalid data is
-    #   added to the tree. Only disable checks with benchmark data that justifies
-    #   the risk.
+    #   disable validation checks for performance-critical usage. Some baseline
+    #   guards (nil children, duplicate child names) are always enforced to
+    #   avoid corrupting the tree. Disabling checks is risky and can lead to
+    #   unexpected behavior if invalid data is added to the tree. Only disable
+    #   checks with benchmark data that justifies the risk.
     #
     # @raise [ArgumentError] Raised if the node name is empty.
     #

lib/tree/utils/structure_methods.rb

@@ -143,9 +143,9 @@ def freeze_tree!
       end
 
       def validate_add_child!(child)
+        raise ArgumentError, 'Attempting to add a nil node' unless child
         return unless checks_enabled?
 
-        raise ArgumentError, 'Attempting to add a nil node' unless child
         raise ArgumentError, 'Attempting add node to itself' if equal?(child)
         raise ArgumentError, 'Attempting add root as a child' if child.equal?(root)
 
@@ -155,8 +155,6 @@ def validate_add_child!(child)
       end
 
       def ensure_unique_child_name!(child)
-        return unless checks_enabled?
-
         return unless @children_hash.include?(child.name)
 
         raise "Child #{child.name} already added!"

test/test_tree_checks.rb

@@ -36,15 +36,24 @@ module TestTree
   class TestTreeChecks < Test::Unit::TestCase
     def test_checks_disabled_skips_validation
       root = Tree::TreeNode.new('root', nil, { checks: false })
-      child1 = Tree::TreeNode.new('dup', nil, { checks: false })
-      child2 = Tree::TreeNode.new('dup', nil, { checks: false })
+      child1 = Tree::TreeNode.new('dup-1', nil, { checks: false })
+      child2 = Tree::TreeNode.new('dup-2', nil, { checks: false })
 
       root.add(child1)
       assert_nothing_raised { root.add(child2) }
       assert_equal(2, root.children.size)
       assert_nil(root[nil])
     end
 
+    def test_checks_disabled_still_enforces_duplicate_names
+      root = Tree::TreeNode.new('root', nil, { checks: false })
+      child1 = Tree::TreeNode.new('dup', nil, { checks: false })
+      child2 = Tree::TreeNode.new('dup', nil, { checks: false })
+
+      root.add(child1)
+      assert_raise(RuntimeError) { root.add(child2) }
+    end
+
     def test_checks_enabled_validation_guards
       root = Tree::TreeNode.new('root')
       child1 = Tree::TreeNode.new('dup')
@@ -72,8 +81,8 @@ def test_checks_setting_propagates_to_children
       root.add(child)
       assert_equal(false, child.checks_enabled?)
 
-      dup = Tree::TreeNode.new('child')
-      assert_nothing_raised { root.add(dup) }
+      other = Tree::TreeNode.new('child2')
+      assert_nothing_raised { root.add(other) }
     end
   end
 end