Refactoring (#31)

### Build and Continuous Integration
- Replaced the Makefile with a bash `make` script. The previous targets were all PHONY, and the Makefile syntax wasn't ideal.
- Added GitHub Actions for continuous integration and automation.

### Go Environment and Tools
- Integrated Go ecosystem tools for quality assurance, including `mod`, `fmt`, `vet`, `lint`, `staticcheck`, `vulncheck`, and `gogec`.
- Updated `go.mod` to Go version 1.18.
- Updated Go dependencies.

### Code Refactoring
- Simplified node structures and merged the `zeroChild` field into the `children` field.
- Simplified code by eliminating bit operations for certain nodes.
- Merged similar functionality between the `ForEach` method and the `Iterator.`
- Split `node.go` and `tree.go` into separate files for improved modularity.
- Refactored and simplified tree iteration and traversal functionality.
- Refactored and simplified the `String` method for the tree.

### Testing and Quality Assurance
- Introduced golden files for tests.
- Added `t.Parallel` for running tests in parallel.
- Refactored some tests for better coverage and readability.

### Code Quality
- Fixed numerous Go lint warnings.
- Added comments to internal code for clarity.
- Renamed variables and method names to improve readability. (After all, cache invalidation and naming things are the two hard things in computer science. :)

**This refactoring effort enhances code structure and quality without altering the external interface/public API.**
---------

Signed-off-by: Pavel Larkin <laxkin@gmail.com>

Author: plar

.github/workflows/go.yml

@@ -1,28 +1,68 @@
-# This workflow will build a golang project
-# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-go
-
 name: Go
 
 on:
   push:
-    branches: [ "master" ]
+    branches:
+      - '*'
   pull_request:
-    branches: [ "master" ]
+    branches:
+      - '*'
 
 jobs:
-
   build:
-    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        go: ['stable', 'oldstable']
+        os: ['ubuntu-latest']
+        
+    runs-on: ${{ matrix.os }}
+    
+    name: Go ${{ matrix.go }} in ${{ matrix.os }}
+    
     steps:
     - uses: actions/checkout@v4
 
-    - name: Set up Go
-      uses: actions/setup-go@v4
+    - uses: actions/setup-go@v5
+      name: Install Go
       with:
-        go-version: '1.20'
+        go-version: ${{ matrix.go }}
+        check-latest: true
+        cache: true
+    
+    - name: Install dependencies
+      run: go get .
+
+    - name: "Run go mod"
+      run: ./make qa/mod
+
+    - name: "Run go fmt"
+      run: ./make qa/fmt
+
+    - name: "Run go vet"
+      run: ./make qa/vet
+
+    - name: "Run go lint"
+      run: ./make qa/lint
 
-    - name: Build
-      run: go build -v ./...
+    - name: "Run go staticcheck"
+      run: ./make qa/staticcheck
+
+    - name: "Run go vulncheck"
+      run: ./make qa/vulncheck
+
+    - name: "Run go gosec"
+      run: ./make qa/gosec
+
+    - name: "Run tests"
+      run: ./make qa/test/cover
+
+    - name: "Rename coverage report to art.coverage.${{ matrix.go }}.${{ matrix.os }}.html..."
+      run: mv ./art.coverage.html art.coverage.${{ matrix.go }}.${{ matrix.os }}.html
+
+    - uses: actions/upload-artifact@v4
+      with:
+        name: art.coverage.${{ matrix.go }}.${{ matrix.os }}
+        path: art.coverage.${{ matrix.go }}.${{ matrix.os }}.html
 
-    - name: Test
-      run: go test -v ./...
+    - name: "Run go benchmarks"
+      run: ./make qa/benchmarks

.golangci.yaml

@@ -0,0 +1,40 @@
+linters:
+  enable-all: true
+
+  disable:
+    - testpackage
+    - ireturn
+    - varnamelen
+    - gofumpt
+    - exhaustruct
+
+issues:  
+  exclude-files:  
+    - tree_dump*
+
+linters-settings:
+  depguard:
+    rules:
+      main:
+        files:
+          - $all
+          - "!$test"
+        allow:
+          - $gostd
+          - github.com/google # all google packages
+      test:
+        files:
+          - "$test"
+        allow:
+          - $gostd
+          - github.com/stretchr
+  exhaustruct:
+    exclude:
+      - ".*_test.go"
+
+output:
+  sort-results: true
+  sort-order:
+    - file # filepath, line, and column.
+    - severity
+    - linter

api.go

@@ -2,7 +2,7 @@ package art
 
 import "errors"
 
-// A constant exposing all node types.
+// Node types.
 const (
 	Leaf    Kind = 0
 	Node4   Kind = 1
@@ -25,13 +25,18 @@ const (
 
 // These errors can be returned when iteration over the tree.
 var (
-	ErrConcurrentModification = errors.New("Concurrent modification has been detected")
-	ErrNoMoreNodes            = errors.New("There are no more nodes in the tree")
+	ErrConcurrentModification = errors.New("concurrent modification has been detected")
+	ErrNoMoreNodes            = errors.New("there are no more nodes in the tree")
 )
 
 // Kind is a node type.
 type Kind int
 
+// String returns string representation of the Kind value.
+func (k Kind) String() string {
+	return []string{"Leaf", "Node4", "Node16", "Node48", "Node256"}[k]
+}
+
 // Key Type.
 // Key can be a set of any characters include unicode chars with null bytes.
 type Key []byte
@@ -100,19 +105,18 @@ type Tree interface {
 	// Iterator returns an iterator for preorder traversal over leaf nodes by default.
 	// Pass TraverseXXX as an options to return an iterator for preorder traversal over all NodeXXX types.
 	Iterator(options ...int) Iterator
-	//IteratorPrefix(key Key) Iterator
 
 	// Minimum returns the minimum valued leaf, true if leaf is found and nil, false otherwise.
-	Minimum() (min Value, found bool)
+	Minimum() (Value, bool)
 
 	// Maximum returns the maximum valued leaf, true if leaf is found and nil, false otherwise.
-	Maximum() (max Value, found bool)
+	Maximum() (Value, bool)
 
 	// Returns size of the tree
 	Size() int
 }
 
-// New creates a new adaptive radix tree
+// New creates a new adaptive radix tree.
 func New() Tree {
 	return newTree()
 }

consts.go

@@ -1,21 +1,21 @@
 package art
 
-// node constraints
+// node constraints.
 const (
-	node4Min = 2
-	node4Max = 4
+	node4Min = 2 // minimum number of children for node4.
+	node4Max = 4 // maximum number of children for node4.
 
-	node16Min = node4Max + 1
-	node16Max = 16
+	node16Min = node4Max + 1 // minimum number of children for node16.
+	node16Max = 16           // maximum number of children for node16.
 
-	node48Min = node16Max + 1
-	node48Max = 48
+	node48Min = node16Max + 1 // minimum number of children for node48.
+	node48Max = 48            // maximum number of children for node48.
 
-	node256Min = node48Max + 1
-	node256Max = 256
+	node256Min = node48Max + 1 // minimum number of children for node256.
+	node256Max = 256           // maximum number of children for node256.
 )
 
 const (
-	// MaxPrefixLen is maximum prefix length for internal nodes.
-	MaxPrefixLen = 10
+	// maxPrefixLen is maximum prefix length for internal nodes.
+	maxPrefixLen = 10
 )

doc.go

@@ -5,39 +5,38 @@
 //
 // Usage
 //
-//  package main
-//
-//  import (
-//     "fmt"
-//     "github.com/plar/go-adaptive-radix-tree"
-//  )
-//
-//  func main() {
-//
-//     tree := art.New()
-//
-//     tree.Insert(art.Key("Hi, I'm Key"), "Nice to meet you, I'm Value")
-//     value, found := tree.Search(art.Key("Hi, I'm Key"))
-//     if found {
-//         fmt.Printf("Search value=%v\n", value)
-//     }
-//
-//     tree.ForEach(func(node art.Node) bool {
-//         fmt.Printf("Callback value=%v\n", node.Value())
-//         return true
-//     }
-//
-//     for it := tree.Iterator(); it.HasNext(); {
-//         value, _ := it.Next()
-//         fmt.Printf("Iterator value=%v\n", value.Value())
-//     }
-//  }
-//
-//  // Output:
-//  // Search value=Nice to meet you, I'm Value
-//  // Callback value=Nice to meet you, I'm Value
-//  // Iterator value=Nice to meet you, I'm Value
-//
+//	package main
+//
+//	import (
+//	   "fmt"
+//	   "github.com/plar/go-adaptive-radix-tree"
+//	)
+//
+//	func main() {
+//
+//	   tree := art.New()
+//
+//	   tree.Insert(art.Key("Hi, I'm Key"), "Nice to meet you, I'm Value")
+//	   value, found := tree.Search(art.Key("Hi, I'm Key"))
+//	   if found {
+//	       fmt.Printf("Search value=%v\n", value)
+//	   }
+//
+//	   tree.ForEach(func(node art.Node) bool {
+//	       fmt.Printf("Callback value=%v\n", node.Value())
+//	       return true
+//	   }
+//
+//	   for it := tree.Iterator(); it.HasNext(); {
+//	       value, _ := it.Next()
+//	       fmt.Printf("Iterator value=%v\n", value.Value())
+//	   }
+//	}
+//
+//	// Output:
+//	// Search value=Nice to meet you, I'm Value
+//	// Callback value=Nice to meet you, I'm Value
+//	// Iterator value=Nice to meet you, I'm Value
 //
 // Also the current implementation was inspired by [2] and [3]
 //

factory.go

@@ -4,51 +4,85 @@ import (
 	"unsafe"
 )
 
+// nodeFactory is an interface for creating various types of ART nodes,
+// including nodes with different capacities and leaf nodes.
 type nodeFactory interface {
-	newNode4() *artNode
-	newNode16() *artNode
-	newNode48() *artNode
-	newNode256() *artNode
-	newLeaf(key Key, value interface{}) *artNode
+	newNode4() *nodeRef
+	newNode16() *nodeRef
+	newNode48() *nodeRef
+	newNode256() *nodeRef
+
+	newLeaf(key Key, value interface{}) *nodeRef
 }
 
-// make sure that objFactory implements all methods of nodeFactory interface
+// make sure that objFactory implements all methods of nodeFactory interface.
 var _ nodeFactory = &objFactory{}
 
-var factory = newObjFactory()
+//nolint:gochecknoglobals
+var (
+	factory = newObjFactory()
+)
 
+// newTree creates a new tree.
 func newTree() *tree {
-	return &tree{}
+	return &tree{
+		version: 0,
+		root:    nil,
+		size:    0,
+	}
 }
 
+// objFactory implements nodeFactory interface.
 type objFactory struct{}
 
+// newObjFactory creates a new objFactory.
 func newObjFactory() nodeFactory {
 	return &objFactory{}
 }
 
-// Simple obj factory implementation
-func (f *objFactory) newNode4() *artNode {
-	return &artNode{kind: Node4, ref: unsafe.Pointer(new(node4))}
+// Simple obj factory implementation.
+func (f *objFactory) newNode4() *nodeRef {
+	return &nodeRef{
+		kind: Node4,
+		ref:  unsafe.Pointer(new(node4)), //#nosec:G103
+	}
 }
 
-func (f *objFactory) newNode16() *artNode {
-	return &artNode{kind: Node16, ref: unsafe.Pointer(&node16{})}
+// newNode16 creates a new node16 as a nodeRef.
+func (f *objFactory) newNode16() *nodeRef {
+	return &nodeRef{
+		kind: Node16,
+		ref:  unsafe.Pointer(new(node16)), //#nosec:G103
+	}
 }
 
-func (f *objFactory) newNode48() *artNode {
-	return &artNode{kind: Node48, ref: unsafe.Pointer(&node48{})}
+// newNode48 creates a new node48 as a nodeRef.
+func (f *objFactory) newNode48() *nodeRef {
+	return &nodeRef{
+		kind: Node48,
+		ref:  unsafe.Pointer(new(node48)), //#nosec:G103
+	}
 }
 
-func (f *objFactory) newNode256() *artNode {
-	return &artNode{kind: Node256, ref: unsafe.Pointer(&node256{})}
+// newNode256 creates a new node256 as a nodeRef.
+func (f *objFactory) newNode256() *nodeRef {
+	return &nodeRef{
+		kind: Node256,
+		ref:  unsafe.Pointer(new(node256)), //#nosec:G103
+	}
 }
 
-func (f *objFactory) newLeaf(key Key, value interface{}) *artNode {
-	clonedKey := make(Key, len(key))
-	copy(clonedKey, key)
-	return &artNode{
+// newLeaf creates a new leaf node as a nodeRef.
+// It clones the key to avoid any source key mutation.
+func (f *objFactory) newLeaf(key Key, value interface{}) *nodeRef {
+	keyClone := make(Key, len(key))
+	copy(keyClone, key)
+
+	return &nodeRef{
 		kind: Leaf,
-		ref:  unsafe.Pointer(&leaf{key: clonedKey, value: value}),
+		ref: unsafe.Pointer(&leaf{ //#nosec:G103
+			key:   keyClone,
+			value: value,
+		}),
 	}
 }