Add API guardrail tests across all tree families

Introduce method-surface and behavior-contract tests for ordered node trees, heaps, key/value trees, aggregate trees, and trie APIs to lock current public behavior before consistency/refactor work.

Author: evolve75

test/test_api_consistency_matrix.rb

@@ -0,0 +1,135 @@
+# test_api_consistency_matrix.rb - This file is part of the RubyTree package.
+#
+# Copyright (c) 2026 Anupam Sengupta
+#
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without modification,
+# are permitted provided that the following conditions are met:
+#
+# - Redistributions of source code must retain the above copyright notice, this
+#   list of conditions and the following disclaimer.
+#
+# - Redistributions in binary form must reproduce the above copyright notice, this
+#   list of conditions and the following disclaimer in the documentation and/or
+#   other materials provided with the distribution.
+#
+# - Neither the name of the organization nor the names of its contributors may
+#   be used to endorse or promote products derived from this software without
+#   specific prior written permission.
+#
+#   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+# ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+# ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+# frozen_string_literal: true
+
+require 'test/unit'
+require_relative '../lib/tree/aatree'
+require_relative '../lib/tree/avltree'
+require_relative '../lib/tree/binaryheap'
+require_relative '../lib/tree/binarymaxheap'
+require_relative '../lib/tree/binarysearchtree'
+require_relative '../lib/tree/btree'
+require_relative '../lib/tree/fenwicktree'
+require_relative '../lib/tree/intervaltree'
+require_relative '../lib/tree/orderstatistictree'
+require_relative '../lib/tree/redblacktree'
+require_relative '../lib/tree/segmenttree'
+require_relative '../lib/tree/splaytree'
+require_relative '../lib/tree/treap'
+require_relative '../lib/tree/trie'
+
+module TestTree
+  # API consistency guardrails by semantic family.
+  class TestApiConsistencyMatrix < Test::Unit::TestCase
+    def test_ordered_node_tree_method_surface
+      required = %i[insert add search delete key]
+
+      [
+        Tree::BinarySearchTreeNode.new('root', 10),
+        Tree::AvlTreeNode.new('root', 10),
+        Tree::RedBlackTreeNode.new('root', 10),
+        Tree::SplayTreeNode.new('root', 10),
+        Tree::TreapNode.new('root', 10),
+        Tree::OrderStatisticTreeNode.new('root', 10),
+        Tree::IntervalTreeNode.new('root', 10..20)
+      ].each do |tree|
+        assert_methods_present(tree, required)
+      end
+    end
+
+    def test_heap_tree_method_surface
+      required = %i[insert add peek extract search delete key]
+
+      [
+        Tree::BinaryHeapNode.new('root', 10),
+        Tree::BinaryMaxHeapNode.new('root', 10)
+      ].each do |tree|
+        assert_methods_present(tree, required)
+      end
+    end
+
+    def test_key_value_tree_method_surface
+      required = %i[
+        insert << search delete [] []= size length each keys values to_a to_h
+        as_json to_json <=>
+      ]
+      class_methods = %i[from_hash json_create]
+
+      [Tree::AATree.new, Tree::BTree.new].each do |tree|
+        assert_methods_present(tree, required)
+        assert_methods_present(tree.class, class_methods)
+      end
+    end
+
+    def test_aggregate_tree_method_surface
+      required = %i[
+        length each update range_sum [] []= keys values to_a to_h as_json
+        to_json <=>
+      ]
+      class_methods = %i[from_hash json_create]
+
+      [Tree::FenwickTree.new(3), Tree::SegmentTree.new(3)].each do |tree|
+        assert_methods_present(tree, required)
+        assert_methods_present(tree.class, class_methods)
+      end
+
+      assert_equal(true, Tree::FenwickTree.new(3).respond_to?(:sum))
+      assert_equal(true, Tree::SegmentTree.new(3).respond_to?(:sum))
+    end
+
+    def test_trie_method_surface
+      trie = Tree::TrieNode.new('')
+      required = %i[
+        insert << include? prefix? delete delete? words_with_prefix terminal?
+      ]
+
+      assert_methods_present(trie, required)
+    end
+
+    def test_intentionally_absent_shovel_for_array_backed_trees
+      assert_equal(false, Tree::FenwickTree.new(3).respond_to?(:<<))
+      assert_equal(false, Tree::SegmentTree.new(3).respond_to?(:<<))
+    end
+
+    private
+
+    def assert_methods_present(target, methods)
+      methods.each do |method_name|
+        assert_equal(
+          true,
+          target.respond_to?(method_name),
+          "Expected #{target.class} to respond to ##{method_name}"
+        )
+      end
+    end
+  end
+end

test/test_api_contracts_aggregate_trees.rb

@@ -0,0 +1,92 @@
+# test_api_contracts_aggregate_trees.rb - This file is part of the RubyTree package.
+#
+# Copyright (c) 2026 Anupam Sengupta
+#
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without modification,
+# are permitted provided that the following conditions are met:
+#
+# - Redistributions of source code must retain the above copyright notice, this
+#   list of conditions and the following disclaimer.
+#
+# - Redistributions in binary form must reproduce the above copyright notice, this
+#   list of conditions and the following disclaimer in the documentation and/or
+#   other materials provided with the distribution.
+#
+# - Neither the name of the organization nor the names of its contributors may
+#   be used to endorse or promote products derived from this software without
+#   specific prior written permission.
+#
+#   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+# ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+# ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+# frozen_string_literal: true
+
+require 'test/unit'
+require_relative '../lib/tree/fenwicktree'
+require_relative '../lib/tree/segmenttree'
+
+module TestTree
+  # Contract tests for aggregate trees.
+  class TestApiContractsAggregateTrees < Test::Unit::TestCase
+    def test_fenwick_contract
+      tree = Tree::FenwickTree.new(4, [1, 2, 3, 4])
+
+      assert_nil(tree.update(2, 5))
+      assert_equal(11, tree.sum(2))
+      assert_equal(14, tree.range_sum(1, 3))
+
+      stored = tree.send(:[]=, 0, 2)
+      assert_equal(tree[0], stored)
+      assert_kind_of(Enumerator, tree.each)
+      assert_equal([0, 1, 2, 3], tree.keys)
+      assert_equal(false, tree.respond_to?(:<<))
+      assert_raise(NoMethodError) { tree << 1 }
+    end
+
+    def test_segment_contract
+      tree = Tree::SegmentTree.new(4, [1, 2, 3, 4])
+
+      assert_kind_of(Numeric, tree.update(2, 10))
+      assert_equal(16, tree.range_sum(1, 3))
+
+      stored = tree.send(:[]=, 0, 8)
+      assert_equal(tree[0], stored)
+      assert_kind_of(Enumerator, tree.each)
+      assert_equal([0, 1, 2, 3], tree.keys)
+      assert_equal(false, tree.respond_to?(:<<))
+      assert_raise(NoMethodError) { tree << 1 }
+    end
+
+    def test_aggregate_tree_serialization_contract
+      [Tree::FenwickTree.new(3, [1, 2, 3]), Tree::SegmentTree.new(3, [1, 2, 3])].each do |tree|
+        hash = tree.to_h
+        rebuilt = tree.class.from_hash(hash)
+
+        assert_equal(tree.to_a, rebuilt.to_a)
+        assert_equal(hash, tree.as_json)
+        assert_equal(tree.to_a, tree.class.json_create(hash).to_a)
+      end
+    end
+
+    def test_aggregate_tree_validation_contract
+      assert_raise(ArgumentError) { Tree::FenwickTree.new(0) }
+      assert_raise(ArgumentError) { Tree::SegmentTree.new(0) }
+
+      fenwick = Tree::FenwickTree.new(2)
+      segment = Tree::SegmentTree.new(2)
+
+      assert_raise(ArgumentError) { fenwick.update(0, nil) }
+      assert_raise(ArgumentError) { segment.update(0, nil) }
+    end
+  end
+end

test/test_api_contracts_heaps.rb

@@ -0,0 +1,81 @@
+# test_api_contracts_heaps.rb - This file is part of the RubyTree package.
+#
+# Copyright (c) 2026 Anupam Sengupta
+#
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without modification,
+# are permitted provided that the following conditions are met:
+#
+# - Redistributions of source code must retain the above copyright notice, this
+#   list of conditions and the following disclaimer.
+#
+# - Redistributions in binary form must reproduce the above copyright notice, this
+#   list of conditions and the following disclaimer in the documentation and/or
+#   other materials provided with the distribution.
+#
+# - Neither the name of the organization nor the names of its contributors may
+#   be used to endorse or promote products derived from this software without
+#   specific prior written permission.
+#
+#   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+# ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+# ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+# frozen_string_literal: true
+
+require 'test/unit'
+require_relative '../lib/tree/binaryheap'
+require_relative '../lib/tree/binarymaxheap'
+
+module TestTree
+  # Contract tests for heap trees.
+  class TestApiContractsHeaps < Test::Unit::TestCase
+    def test_min_heap_contract
+      root = Tree::BinaryHeapNode.new('root', 10)
+      root.insert('n5', 5)
+      root.add(Tree::BinaryHeapNode.new('n20', 20))
+
+      assert_equal(5, root.peek)
+      assert_equal(5, root.extract)
+      assert_equal(10, root.peek)
+
+      found = root.search(20)
+      assert_kind_of(Tree::BinaryHeapNode, found)
+
+      removed = root.delete(20)
+      assert_kind_of(Tree::BinaryHeapNode, removed)
+      assert_nil(root.search(20))
+    end
+
+    def test_max_heap_contract
+      root = Tree::BinaryMaxHeapNode.new('root', 10)
+      root.insert('n5', 5)
+      root.add(Tree::BinaryMaxHeapNode.new('n20', 20))
+
+      assert_equal(20, root.peek)
+      assert_equal(20, root.extract)
+      assert_equal(10, root.peek)
+
+      found = root.search(5)
+      assert_kind_of(Tree::BinaryMaxHeapNode, found)
+
+      removed = root.delete(5)
+      assert_kind_of(Tree::BinaryMaxHeapNode, removed)
+      assert_nil(root.search(5))
+    end
+
+    def test_heap_key_and_nil_key_validation
+      root = Tree::BinaryHeapNode.new('root', 10)
+      assert_equal(10, root.key)
+      assert_raise(ArgumentError) { root.search(nil) }
+    end
+  end
+end