If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/emirpasic/gods shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 1y ago

• 7 active contributors
• Other licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 1y ago
• ⚠ Single-maintainer risk — top contributor 93% of recent commits
• ⚠ Non-standard license (Other) — review terms

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live emirpasic/gods repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/emirpasic/gods.

What it runs against: a local clone of emirpasic/gods — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in emirpasic/gods | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 454 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of emirpasic/gods. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/emirpasic/gods.git
#   cd gods
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of emirpasic/gods and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "emirpasic/gods(\\.git)?\\b" \\
  && ok "origin remote is emirpasic/gods" \\
  || miss "origin remote is not emirpasic/gods (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "containers/containers.go" \\
  && ok "containers/containers.go" \\
  || miss "missing critical file: containers/containers.go"
test -f "containers/iterator.go" \\
  && ok "containers/iterator.go" \\
  || miss "missing critical file: containers/iterator.go"
test -f "lists/lists.go" \\
  && ok "lists/lists.go" \\
  || miss "missing critical file: lists/lists.go"
test -f "maps/maps.go" \\
  && ok "maps/maps.go" \\
  || miss "missing critical file: maps/maps.go"
test -f "containers/enumerable.go" \\
  && ok "containers/enumerable.go" \\
  || miss "missing critical file: containers/enumerable.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 454 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~424d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/emirpasic/gods"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

GoDS is a comprehensive Go library implementing 15+ classic data structures (lists, sets, maps, trees, queues, stacks) with a unified Container interface and stateful iterators. It solves the problem of Go's lack of built-in generic collections by providing production-ready, well-tested implementations of ArrayList, HashSet, TreeMap, AVLTree, BinaryHeap, RedBlackTree, and others that work with interface{} values. Monorepo structure: containers/containers.go defines the unified Container interface; data structure implementations are split across separate subdirectories (lists/, sets/, maps/, trees/, queues/); examples/ contains executable demos for each structure (e.g., examples/avltree/avltree.go). Tests are co-located as *_test.go files. No internal dependencies—each structure is self-contained.

Go backend engineers and systems programmers who need efficient, reusable data structures for algorithms, caching layers, priority queues, or ordered collections without writing custom implementations. Contributors are typically computer science students or library maintainers building foundational utilities.

Production-ready and actively maintained. The project has CircleCI/CodeQL CI/CD, high test coverage (codecov badge present), follows Go 1.21+ module standards, and the modular example structure suggests stable APIs. However, GoDS predates Go 1.18 generics, so it uses interface{} instead of type parameters—a design choice that limits type safety but hasn't prevented adoption.

Low operational risk but moderate technical debt: the library uses interface{} everywhere instead of Go generics (available since 1.18), making it less type-safe than modern Go codebases. Single maintainer (emirpasic) is a potential concern for critical bugs. No evidence of breaking API changes in recent commits, and the stable container interface mitigates this. Zero external dependencies reduces supply-chain risk.

The project is in stable maintenance mode. Recent activity shows Dependabot managing dependencies and CodeQL security scanning via GitHub Actions. The file structure reflects a mature, feature-complete library with all major data structures implemented. No active development of new structures is evident from the file list, but maintenance and bug fixes are ongoing.

Clone the repo and verify with Go 1.21+: git clone https://github.com/emirpasic/gods.git && cd gods && go mod download && go test ./... to run the full test suite. Explore examples with go run examples/arraylist/arraylist.go to see concrete usage patterns.

Daily commands: This is a library, not a runnable server. To test locally: go test ./... runs all unit tests. To explore: go run examples/binaryheap/binaryheap.go runs a specific example. Each example is a standalone .go file in examples/ with a main() function.

• containers/containers.go — Defines the core Container interface that all data structures implement; foundational abstraction for the entire library
• containers/iterator.go — Specifies Iterator interface used across all collections; essential for understanding how traversal works throughout GoDS
• lists/lists.go — Defines List interface contract; entry point for understanding list-based data structures in the library
• maps/maps.go — Defines Map interface contract; entry point for all map-based implementations
• containers/enumerable.go — Specifies Enumerable interface for functional operations (Map, Filter, etc.); critical for functional programming patterns
• go.mod — Declares module as github.com/emirpasic/gods/v2 with Go 1.21 requirement; all dependency management centralized here

• Container interface (Go interfaces, generic-style design) — Base contract for all collections: Size(), Empty(), Clear(), Values()

Add a new List implementation

1. Create new package directory under lists/ (e.g., lists/skiplist/) (lists/skiplist/skiplist.go)
2. Implement the List interface from lists/lists.go (Get, Set, Insert, Remove, etc.) (lists/skiplist/skiplist.go)
3. Add iterator support by implementing iterator.go following patterns from lists/arraylist/iterator.go (lists/skiplist/iterator.go)
4. Implement enumerable operations by referencing lists/arraylist/enumerable.go (lists/skiplist/enumerable.go)
5. Add serialization support via lists/skiplist/serialization.go following containers/serialization.go pattern (lists/skiplist/serialization.go)
6. Create comprehensive test suite with _test.go suffix (lists/skiplist/skiplist_test.go)
7. Add executable example demonstrating key operations (examples/skiplist/skiplist.go)

Add a new Map implementation

1. Create new package directory under maps/ (e.g., maps/concurrentmap/) (maps/concurrentmap/concurrentmap.go)
2. Implement the Map interface from maps/maps.go (Put, Get, Remove, Contains, Keys, Values) (maps/concurrentmap/concurrentmap.go)
3. Add iterator support following maps/hashmap or maps/linkedhashmap pattern (maps/concurrentmap/iterator.go)
4. Implement enumerable operations if ordered traversal is required (maps/concurrentmap/enumerable.go)
5. Add serialization support following maps/hashmap/serialization.go pattern (maps/concurrentmap/serialization.go)
6. Create test file verifying all Map interface contracts (maps/concurrentmap/concurrentmap_test.go)

Add a custom comparator for sorted structures

1. Define a Comparator function type matching int(a, b) int pattern used in examples/customcomparator/ (examples/customcomparator/customcomparator.go)
2. Pass comparator to TreeMap or TreeSet constructor; see maps/treemap/treemap.go for signature (maps/treemap/treemap.go)
3. Comparator must return <0 if a<b, 0 if a==b, >0 if a>b for red-black tree operations (examples/customcomparator/customcomparator.go)

• Go generics (implied by v2 branch with go 1.21) — Enables type-safe data structures without reflection overhead; compile-time type checking matches Go 1.21+ capabilities
• Interface-based design (Container, Iterator, Enumerable) — Allows multiple implementations (e.g., ArrayList vs LinkedList) to satisfy same contract; enables duck typing and loose coupling
• Red-Black Trees for sorted collections — Self-balancing guarantees O(log n) operations and maintains sorted order; better than hash maps when order matters
• Hash-based maps with linked list overlay (LinkedHashMap) — Combines O(1) hash lookup with O(n) iteration in insertion order; bridges performance and predictability

• Provide both ArrayList and doublylinkedlist/singlylinkedlist

  • Why: Different use cases require different access patterns
  • Consequence: O(1) random access (ArrayList) vs O(1) insertion/deletion anywhere (LinkedList); users must choose based on workload

• Separate HashMap (unordered) and TreeMap (sorted) instead of single adaptive structure

  • Why: Keeps code simpler and avoids runtime overhead for ordered iteration
  • Consequence: Users must explicitly choose between speed (HashMap) and order guarantees (TreeMap)

• Implement Enumerable with functional operations (Map, Filter, Reduce)

  • Why: Matches modern Go idioms and reduces boilerplate
  • Consequence: Creates intermediate collections; less memory-efficient than iterator-based approach for large datasets

• Support JSON serialization at collection level, not element level

  • Why: Simpler interface; puts marshaling burden on caller for custom types
  • Consequence: Users must implement custom JSON codecs for complex element types; less magic but more work

• Thread-safe concurrent access (no synchronization primitives in collections)
• Streaming/lazy evaluation (Enumerable eagerly materializes results)
• Generic constraint-based validation (int, string, custom types allowed but not validated)
• Memory pooling or allocation optimization

No hidden environment variables or service dependencies. Key gotcha: all containers work with interface{} values, so you must type-assert on retrieval (e.g., list.Get(0).(int))—forgetting this causes runtime panics. The Comparator interface is required for ordered structures (TreeSet, TreeMap, AVLTree); passing nil will panic. Custom comparators must return -1/0/1 consistently or ordered structures will corrupt. No thread-safe variants—concurrent access requires external synchronization (sync.RWMutex).

• Red-Black Tree — Powers TreeMap and TreeSet in GoDS, ensuring O(log n) lookups with automatic balancing; understanding this data structure explains why ordered maps are slower than hash maps but support range queries.
• AVL Tree — An alternative self-balancing binary search tree available in GoDS with tighter balance guarantees than Red-Black trees, relevant when minimizing tree height is critical.
• B-Tree — GoDS implements B-Trees for scenarios with high branching factors and disk I/O, essential for understanding when to prefer BTree over binary search trees.
• Binary Heap — Underlies PriorityQueue in GoDS; understanding heap operations (bubble-up/down) is critical for implementing Dijkstra's algorithm and priority-based scheduling.
• Bidirectional Map (BiMap) — GoDS provides HashBidiMap and TreeBidiMap, which maintain forward and reverse key-value lookups simultaneously; useful for user ID ↔ username caching.
• Circular Buffer — GoDS's CircularBuffer implementation provides fixed-size, efficient FIFO behavior without reallocation; critical for embedded systems and ring buffer use cases.
• Comparator Pattern — GoDS uses injected comparators (passed to ordered structures) rather than relying on built-in comparison operators, enabling custom ordering logic without modifying container code.

• golang/go — Official Go repository where generics were added in Go 1.18; GoDS could evolve to use them instead of interface{}.
• google/btree — Google's optimized B-tree implementation for Go; a more specialized alternative for range-query workloads than GoDS's BTree.
• zyedidia/generic — Generic Go data structures using type parameters (post-1.18 generics); represents the modern direction that GoDS could migrate toward.
• thoas/go-funk — Complementary Go utility library providing functional programming helpers (Map, Filter, Reduce) that compose well with GoDS containers.
• cespare/xxhash — Fast hashing library often used with GoDS's HashMap and HashSet for improved hash function performance in production systems.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive benchmarking suite for all data structures

The repo has extensive examples and tests but no visible benchmark files (no *_bench_test.go files). Given that GoDS is a performance-critical library providing multiple implementations of similar structures (e.g., ArrayList vs LinkedList, HashMap vs TreeMap, RedBlackTree vs AVLTree), benchmarks would help users understand trade-offs and maintainers catch performance regressions. This is high-value for a data structures library.

• [ ] Create lists/arraylist/arraylist_bench_test.go with benchmarks for Add, Get, Remove operations at various list sizes
• [ ] Create lists/singlylinkedlist/singlylinkedlist_bench_test.go with same operations for comparison
• [ ] Create maps/hashmap/hashmap_bench_test.go and maps/treemap/treemap_bench_test.go benchmarking Put, Get, Remove
• [ ] Create sets/hashset/hashset_bench_test.go and sets/treeset/treeset_bench_test.go for comparison
• [ ] Add benchmark comparison documentation to README.md showing results across implementations
• [ ] Integrate benchmarks into .circleci/config.yml to track performance across commits

Add missing enumerable interface tests for all container implementations

The repo has enumerable.go interfaces defined in containers/ and individual enumerable tests like lists/arraylist/enumerable.go, but examining the file structure shows inconsistent test coverage. Many data structure packages likely lack dedicated *enumerable_test.go files. This is critical because the enumerable interface (Each, Map, Select, etc.) is a core feature of GoDS but may have untested edge cases across different container types.

• [ ] Audit lists/doublylinkedlist/, lists/singlylinkedlist/, and lists/arraylist/ for missing enumerable_test.go files
• [ ] Create sets/hashset/enumerable_test.go and sets/treeset/enumerable_test.go testing Each, Map, Select, Any, All operations
• [ ] Create maps/hashmap/enumerable_test.go and maps/treemap/enumerable_test.go with key-value enumeration tests
• [ ] Create stacks and queues enumerable tests (arraystack, linkedliststack, arrayqueue, linkedlistqueue)
• [ ] Add tests for nil predicates, empty containers, and panic conditions in enumerable operations across all implementations

Implement missing iterator interface tests for bidirectional maps and trees

The repo has IteratorWithKey and IteratorWithIndex interfaces defined, but bidirectional maps (TreeBidiMap, HashBidiMap) and complex tree structures appear to lack comprehensive iterator tests in the file structure. Bidirectional maps require special iteration semantics (forward/reverse directions for key-value pairs), and trees require tests for different traversal orders, making this high-value for correctness.

• [ ] Create maps/hashbidimap/iterator_test.go testing forward/reverse iteration through key-value pairs
• [ ] Create maps/treebidimap/iterator_test.go testing bidirectional iteration and order preservation
• [ ] Create trees/binarysearchtree/iterator_test.go testing in-order, pre-order, post-order traversals (if not present)
• [ ] Create trees/redblacktree/iterator_test.go with comprehensive iterator edge cases and concurrent modification scenarios
• [ ] Add tests for iterator.Next() returning nil, iterator.Prev() for reverse iteration, and index tracking in all iterator implementations
• [ ] Document iterator guarantees and limitations in containers/iterator.go with concrete examples

• Add benchmarks for all data structures in a new benchmarks/ directory (currently only unit tests exist in *_test.go files). This would help users understand performance trade-offs between HashMap vs TreeMap or ArrayList vs DoublyLinkedList.
• Write a comprehensive godoc example file (examples_test.go in each package root) showing all methods for lesser-known structures like TreeBidiMap and LinkedHashSet, since the examples/ directory focuses only on basic usage.
• Implement generic type-safe wrappers (e.g., IntList wrapping ArrayList, StringSet wrapping HashSet) in a new generic/ package that type-assert internally, making the library safer for common use cases while keeping backward compatibility.

The GoDS library demonstrates a strong security posture overall. As a pure data structures library with no external dependencies, network calls, database interactions, or credential handling, it has a minimal attack surface. The codebase contains no hardcoded secrets, suspicious dependencies, injection vulnerabilities, or infrastructure misconfigurations. The primary recommendation is to maintain current Go version compatibility to ensure access to the latest security patches. The project maintains good CI/CD practices with CodeQL analysis enabled and comprehensive test coverage tracking via codecov.

• Low · Missing Go Version Security Recommendations — go.mod. The go.mod file specifies 'go 1.21' which is now outdated. Go 1.21 has reached end-of-support status. While this is a data structures library with no direct web exposure, using outdated Go versions may miss critical security patches and bug fixes. Fix: Update to the latest stable Go version (1.22 or newer). Review the Go release notes for any security-related changes and update accordingly.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.