fix: uncomment and fix CalculateTopRanks, optimize core functions

.github/workflows/test.yml

@@ -29,4 +29,4 @@ jobs:
         run: go vet .
 
       - name: Test
-        run: go test -bench=. -benchmem -v .
+        run: go test -race -bench=. -benchmem -v .

Makefile

@@ -0,0 +1,51 @@
+.PHONY: all build test race vet lint bench fuzz-query fuzz-cp tidy clean help
+
+GO       ?= go
+PKG      ?= ./...
+FUZZTIME ?= 30s
+
+all: vet test
+
+build:
+	$(GO) build $(PKG)
+
+test:
+	$(GO) test $(PKG)
+
+race:
+	$(GO) test -race $(PKG)
+
+vet:
+	$(GO) vet $(PKG)
+
+lint:
+	golangci-lint run
+
+bench:
+	$(GO) test -bench=. -benchmem -run=^$$ $(PKG)
+
+fuzz-query:
+	$(GO) test -run=^$$ -fuzz=FuzzQueryPvPRankBounds -fuzztime=$(FUZZTIME) .
+
+fuzz-cp:
+	$(GO) test -run=^$$ -fuzz=FuzzCalculateCpBounds -fuzztime=$(FUZZTIME) .
+
+tidy:
+	$(GO) mod tidy
+
+clean:
+	$(GO) clean -testcache
+	rm -rf testdata/fuzz
+
+help:
+	@echo "Targets:"
+	@echo "  build       compile package"
+	@echo "  test        run unit tests"
+	@echo "  race        run unit tests with -race"
+	@echo "  vet         go vet"
+	@echo "  lint        golangci-lint run"
+	@echo "  bench       run benchmarks"
+	@echo "  fuzz-query  fuzz QueryPvPRank bounds (FUZZTIME=$(FUZZTIME))"
+	@echo "  fuzz-cp     fuzz CalculateCp bounds (FUZZTIME=$(FUZZTIME))"
+	@echo "  tidy        go mod tidy"
+	@echo "  clean       drop test cache + fuzz corpus"

README.md

@@ -20,11 +20,6 @@ This is a rewrite of node version https://github.com/Mygod/ohbem
 * Optional built-in caching
 * Faster than node :)
 
-## Current State
-
-- `CalculateTopRanks` is broken.
-- Everything else is fine.
-
 ## [Documentation](https://pkg.go.dev/github.com/UnownHash/gohbem)
 
 ## Usage
@@ -58,6 +53,8 @@ func main() {
     levelCaps := []int{50, 51}                                        // Level caps.
 
     ohbem := gohbem.Ohbem{Leagues: leagues, LevelCaps: levelCaps}
+    // Optional: override the upstream MasterFile location (self-hosted / air-gapped).
+    // ohbem.MasterFileURL = "https://example.com/master-latest-basics.json"
 
     err = ohbem.FetchPokemonData()                                    // Fetch latest stable MasterFile...
     err = ohbem.WatchPokemonData()                                    // ...automatically watch remote for changes...
@@ -94,7 +91,7 @@ entries, err := ohbem.QueryPvPRank(605, 0, 0, 1, 1, 4, 12, 7)
 }
 ```
 
-### CalculateTopRanks (broken)
+### CalculateTopRanks
 
 ```go
 entries, err := ohbem.CalculateTopRanks(5, 605, 0, 0, 0)

errors.go

@@ -2,44 +2,56 @@ package gohbem
 
 import "errors"
 
-// ErrNilChannel is returned when o.watcherChan is uninitialized.
-var ErrNilChannel = errors.New("can't close nil channel")
+// User input errors — caller passed something invalid.
+var (
+	// ErrQueryInputOutOfRange is returned when wrong arguments are passed to QueryPvPRank function.
+	ErrQueryInputOutOfRange = errors.New("one of input arguments 'Attack, Defense, Stamina, Level' is out of range")
 
-// ErrMasterFileUnloaded is returned when MasterFile wasn't loaded but there was a need to use it.
-var ErrMasterFileUnloaded = errors.New("masterFile unloaded")
+	// ErrMissingPokemon is returned when Pokemon is missing in MasterFile.
+	ErrMissingPokemon = errors.New("missing pokemonID in MasterFile")
+)
 
-// ErrMasterFileOpen is returned when MasterFile can't be open.
-var ErrMasterFileOpen = errors.New("can't open MasterFile")
+// Runtime state errors — Ohbem instance is not in a usable state.
+var (
+	// ErrMasterFileUnloaded is returned when MasterFile wasn't loaded but there was a need to use it.
+	ErrMasterFileUnloaded = errors.New("masterFile unloaded")
 
-// ErrMasterFileSave is returned when MasterFile can't be saved.
-var ErrMasterFileSave = errors.New("can't save MasterFile")
+	// ErrLeaguesMissing is returned when Leagues configuration is empty.
+	ErrLeaguesMissing = errors.New("leagues configuration is empty")
 
-// ErrMasterFileMarshall is returned when Marshal of MasterFile fail.
-var ErrMasterFileMarshall = errors.New("can't marshal MasterFile")
+	// ErrLevelCapsMissing is returned when levelCaps configuration is empty.
+	ErrLevelCapsMissing = errors.New("levelCaps configuration is empty")
 
-// ErrMasterFileUnmarshall is returned when UnMarshal of MasterFile fail.
-var ErrMasterFileUnmarshall = errors.New("can't unmarshal MasterFile")
+	// ErrNilChannel is returned when o.watcherChan is uninitialized.
+	ErrNilChannel = errors.New("can't close nil channel")
 
-// ErrMasterFileFetch is returned when remote fetch of MasterFile fail.
-var ErrMasterFileFetch = errors.New("can't fetch remote MasterFile")
+	// ErrWatcherStarted is returned when MasterFile Watcher is already running.
+	ErrWatcherStarted = errors.New("MasterFile Watcher Already Started")
+)
 
-// ErrMasterFileDecode is returned when decode of MasterFile fail.
-var ErrMasterFileDecode = errors.New("can't decode remote MasterFile")
+// I/O errors — fetching, loading, or saving the MasterFile failed.
+var (
+	// ErrMasterFileOpen is returned when MasterFile can't be open.
+	ErrMasterFileOpen = errors.New("can't open MasterFile")
 
-// ErrWatcherStarted is returned when MasterFile Watcher is already running.
-var ErrWatcherStarted = errors.New("MasterFile Watcher Already Started")
+	// ErrMasterFileSave is returned when MasterFile can't be saved.
+	ErrMasterFileSave = errors.New("can't save MasterFile")
 
-// ErrQueryInputOutOfRange is returned when wrong arguments are passed to QueryPvPRank function.
-var ErrQueryInputOutOfRange = errors.New("one of input arguments 'Attack, Defense, Stamina, Level' is out of range")
+	// ErrMasterFileMarshall is returned when Marshal of MasterFile fail.
+	ErrMasterFileMarshall = errors.New("can't marshal MasterFile")
 
-// ErrMissingPokemon is returned when Pokemon is missing in MasterFile.
-var ErrMissingPokemon = errors.New("missing pokemonID in MasterFile")
+	// ErrMasterFileUnmarshall is returned when UnMarshal of MasterFile fail.
+	ErrMasterFileUnmarshall = errors.New("can't unmarshal MasterFile")
 
-// ErrPvpStatBestCp is returned when BestCP > Cap in calculatePvPStat function.
-var ErrPvpStatBestCp = errors.New("bestCP > cap")
+	// ErrMasterFileFetch is returned when remote fetch of MasterFile fail.
+	ErrMasterFileFetch = errors.New("can't fetch remote MasterFile")
 
-// ErrLeaguesMissing is returned when Leagues configuration is empty.
-var ErrLeaguesMissing = errors.New("leagues configuration is empty")
+	// ErrMasterFileDecode is returned when decode of MasterFile fail.
+	ErrMasterFileDecode = errors.New("can't decode remote MasterFile")
+)
 
-// ErrLevelCapsMissing is returned when levelCaps configuration is empty.
-var ErrLevelCapsMissing = errors.New("levelCaps configuration is empty")
+// Internal computation errors.
+var (
+	// ErrPvpStatBestCp is returned when BestCP > Cap in calculatePvPStat function.
+	ErrPvpStatBestCp = errors.New("bestCP > cap")
+)