Make Tree no longer extend HashMap

[GumpacG]

Summary

Changes Tree from extends HashMap<T, Tree<T>> to a final class that
holds a Map internally and exposes a tree-shaped public API. Tree is no
longer a Map, which removes inherited Map methods whose behavior did not
align with tree semantics (e.g. size() returned root-entry count, not total
nodes; containsKey only checked immediate children).

Per the dev-list discussion: https://lists.apache.org/thread/o0nqh6kmrkdht531655p351ldjll045d

This is a breaking change targeted at TinkerPop 4.0.0.

Changes

Tree now exposes:

• Navigation: rootNodes(), childAt(key) (throws if absent), hasChild(key),
  contains(value) (recursive), findSubtree(key) (recursive, Optional),
  getOrCreateChild(key) (construction primitive).
• Structure: isLeaf(), nodeCount(), getNodesAtDepth(int),
  getTreesAtDepth(int), getLeafNodes(), getLeafTrees().
• Composition/output: addTree(), splitParents(), prettyPrint(),
  structural equals/hashCode/toString.

Behavior fixes that fall out of the rewrite:

• isLeaf() returns true on an empty tree instead of throwing.
• getNodesAtDepth(0) returns the root nodes (now 0-based).

Internal callers migrated off the removed Map surface:

• TreeStep / TreeSideEffectStep use getOrCreateChild during construction.
• GraphBinary TreeSerializer and GraphSON TreeJacksonSerializer/
  Deserializer (V1–V4) iterate via rootNodes()/childAt() and rebuild via
  getOrCreateChild() + addTree().
• DetachedFactory / ReferenceFactory gained an explicit Tree branch
  (previously handled via the instanceof Map path).

Breaking changes

• Code treating a Tree as a Map (assignment to Map, instanceof Map,
  get/put/keySet/entrySet/size) no longer compiles.
• Gremlin patterns that worked only because Tree was a Map (select(keys),
  count(local), unfold() on a tree) no longer compose; process the result
  client-side after next() or reshape the upstream traversal.

Speed and Memory

Analytical estimates (not benchmarked); the backing HashMap table and entries
are identical before and after.

• Memory: ~16 B more per node — Tree now holds a HashMap instead of
  being one, adding one wrapper object per node. The map itself is unchanged.
• Speed: comparable. Construction is slightly faster (getOrCreateChild is
  1–2 map ops vs. the old 3); childAt is one op slower (collapsible to one).
  Wire-format encoding is unchanged.

Testing

• TreeTest rewritten against the new API (navigation, recursive
  containment/search, depth queries, leaf detection, null keys, structural
  equality, toString, pretty-print); TreeSupplierTest updated.

Assisted-by: Kiro: Claude Opus 4.8

[codecov-commenter]

Codecov Report

❌ Patch coverage is 88.70968% with 21 lines in your changes missing coverage. Please review.
✅ Project coverage is 76.43%. Comparing base (a28cd1f) to head (49bb284).
⚠️ Report is 108 commits behind head on master.

Files with missing lines	Patch %	Lines
...n/structure/io/graphson/GraphSONSerializersV2.java	0.00%	8 Missing ⚠️
...n/structure/io/graphson/GraphSONSerializersV3.java	0.00%	8 Missing ⚠️
...rpop/gremlin/process/traversal/step/util/Tree.java	96.29%	1 Missing and 2 partials ⚠️
...n/structure/io/graphson/GraphSONSerializersV4.java	87.50%	0 Missing and 1 partial ⚠️
...inkerpop/gremlin/groovy/loaders/SugarLoader.groovy	66.66%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##             master    #3448      +/-   ##
============================================
+ Coverage     76.35%   76.43%   +0.07%     
- Complexity    13424    13659     +235     
============================================
  Files          1012     1024      +12     
  Lines         60341    61675    +1334     
  Branches       7075     7208     +133     
============================================
+ Hits          46076    47141    +1065     
- Misses        11548    11680     +132     
- Partials       2717     2854     +137     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[spmallette]

i know we wanted more tree terminology so we moved from "Objects" to "Node", but it just occurred to me that the return here isn't exactly a "node", is it? I wonder if that will be confusing.

[GumpacG]

I agree that it's not exactly a "node" however, renaming to "objects" may make other tree functions not very tree-like. For example, nodeCount() would have to be objectCount() and rootNodes() would have to be rootObjects(). I think it would be more conducive for tree users to keep "node".

[kenhuuu]

VOTE +1

[Cole-Greer]

VOTE +1