feat: implement traversal engine (HAN-380) (#6)

Co-authored-by: Hansen IT Solutions <gary@hansenits.com>
Co-committed-by: Hansen IT Solutions <gary@hansenits.com>

internal/traverse/stack.go

@@ -0,0 +1,58 @@
+package traverse
+
+const DefaultMaxDepth = 20
+
+type Stack struct {
+	items   []*Referral
+	maxDepth int
+}
+
+func NewStack(maxDepth int) *Stack {
+	if maxDepth <= 0 {
+		maxDepth = DefaultMaxDepth
+	}
+	return &Stack{
+		items:   make([]*Referral, 0),
+		maxDepth: maxDepth,
+	}
+}
+
+func (s *Stack) Push(r *Referral) bool {
+	if r == nil {
+		return false
+	}
+	if r.Depth >= s.maxDepth {
+		return false
+	}
+	s.items = append(s.items, r)
+	return true
+}
+
+func (s *Stack) Pop() *Referral {
+	if len(s.items) == 0 {
+		return nil
+	}
+	idx := len(s.items) - 1
+	item := s.items[idx]
+	s.items = s.items[:idx]
+	return item
+}
+
+func (s *Stack) Peek() *Referral {
+	if len(s.items) == 0 {
+		return nil
+	}
+	return s.items[len(s.items)-1]
+}
+
+func (s *Stack) Len() int {
+	return len(s.items)
+}
+
+func (s *Stack) MaxDepth() int {
+	return s.maxDepth
+}
+
+func (s *Stack) IsEmpty() bool {
+	return len(s.items) == 0
+}