Release

.github/workflows/ci.yml

@@ -0,0 +1,51 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: lint (${{ matrix.module }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # Every module has its own go.mod and is linted independently.
+        module: [".", "lfu", "policies", "policies/arc", "policies/tinylfu", "metrics", "bench", "examples/basic", "examples/migration"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.25"
+          cache-dependency-path: ${{ matrix.module }}/go.sum
+      - name: golangci-lint
+        # v7 of the action is required for golangci-lint v2.
+        uses: golangci/golangci-lint-action@v7
+        with:
+          version: v2.8.0
+          working-directory: ${{ matrix.module }}
+
+  test:
+    name: test (${{ matrix.module }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        module: [".", "lfu", "policies", "policies/arc", "policies/tinylfu", "metrics", "bench", "examples/basic", "examples/migration"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.25"
+          cache-dependency-path: ${{ matrix.module }}/go.sum
+      - name: go vet
+        working-directory: ${{ matrix.module }}
+        run: go vet ./...
+      - name: go test
+        working-directory: ${{ matrix.module }}
+        run: go test -race -short -count=1 ./...

.gitignore

@@ -1 +1,12 @@
-*.out
+*.out
+
+# Compiled example binaries (built via `go build` / `go run` in each example dir)
+/examples/basic/basic
+/examples/migration/migration
+
+# cache replay traces: downloaded at test time, never committed
+traces/
+*.trace
+*.trace.gz
+*.spc.bz2
+cluster0*

.golangci.yml

@@ -0,0 +1,82 @@
+# golangci-lint configuration (schema v2).
+# A single root config is discovered by golangci-lint when run from any of the
+# repository's modules (root, lfu, examples/*), so all modules share these rules.
+version: "2"
+
+run:
+  # Lint test files as well as production code.
+  tests: true
+
+linters:
+  # Start from the curated "standard" set (errcheck, govet, ineffassign,
+  # staticcheck, unused) and layer additional checks on top.
+  default: standard
+  enable:
+    - revive # replacement for golint: style and exported-doc checks
+    - gosec # security analysis
+    - misspell # spelling mistakes in comments/strings
+    - unconvert # unnecessary type conversions
+    - unparam # unused function parameters/results
+    - gocritic # opinionated diagnostics, performance and style checks
+    - bodyclose # HTTP response bodies must be closed
+    - errorlint # correct error wrapping / comparison
+    - copyloopvar # obsolete loop-variable copies (Go 1.22+)
+    - prealloc # slices that could be preallocated
+    - nolintlint # keep //nolint directives well-formed and justified
+
+  settings:
+    revive:
+      rules:
+        - name: exported
+        - name: package-comments
+        - name: blank-imports
+        - name: context-as-argument
+        - name: error-return
+        - name: error-strings
+        - name: error-naming
+        - name: if-return
+        - name: indent-error-flow
+        - name: receiver-naming
+        - name: time-naming
+        - name: unreachable-code
+        - name: var-declaration
+    gocritic:
+      enabled-tags:
+        - diagnostic
+        - performance
+        - style
+      disabled-checks:
+        - hugeParam
+        - unnamedResult
+        - rangeValCopy
+
+  exclusions:
+    generated: lax
+    presets:
+      - comments
+      - common-false-positives
+      - std-error-handling
+    # Files excluded from every linter.
+    paths:
+      - policytype_string\.go # generated stringer output
+    rules:
+      # Test files: relax security/allocation/param linters that add noise there.
+      - path: _test\.go
+        linters:
+          - gosec
+          - unparam
+          - prealloc
+      # Examples are teaching material: keep them readable, don't require full
+      # godoc on every exported identifier.
+      - path: examples/
+        linters:
+          - revive
+
+formatters:
+  enable:
+    - gofmt
+    - goimports
+  settings:
+    goimports:
+      local-prefixes:
+        - github.com/sshaplygin/as-cache

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "makefile.configureOnOpen": false
+}

Makefile

@@ -0,0 +1,63 @@
+# Each of these directories is a separate Go module (own go.mod), so tooling is
+# run once per module. The root .golangci.yml is shared by all of them.
+MODULES := . lfu policies policies/arc policies/tinylfu metrics bench examples/basic examples/migration
+
+GOLANGCI_LINT_VERSION := v2.8.0
+
+.PHONY: all
+all: fmt vet lint test ## Format, vet, lint and test
+
+.PHONY: lint
+lint: ## Run golangci-lint across all modules
+	@set -e; for m in $(MODULES); do \
+		echo "==> lint $$m"; \
+		( cd $$m && golangci-lint run ./... ); \
+	done
+
+.PHONY: lint-fix
+lint-fix: ## Run golangci-lint with --fix and apply formatters across all modules
+	@set -e; for m in $(MODULES); do \
+		echo "==> lint-fix $$m"; \
+		( cd $$m && golangci-lint run --fix ./... && golangci-lint fmt ./... ); \
+	done
+
+.PHONY: fmt
+fmt: ## Apply gofmt/goimports via the golangci-lint formatters
+	@set -e; for m in $(MODULES); do \
+		echo "==> fmt $$m"; \
+		( cd $$m && golangci-lint fmt ./... ); \
+	done
+
+.PHONY: vet
+vet: ## Run go vet across all modules
+	@set -e; for m in $(MODULES); do \
+		echo "==> vet $$m"; \
+		( cd $$m && go vet ./... ); \
+	done
+
+.PHONY: test
+test: ## Run tests with the race detector across all modules
+	@set -e; for m in $(MODULES); do \
+		echo "==> test $$m"; \
+		( cd $$m && go test -race -short -count=1 ./... ); \
+	done
+
+.PHONY: evidence
+evidence: ## Replay the workload suite and print the policy comparison tables
+	( cd bench && go test -count=1 -timeout 20m -v ./... )
+
+.PHONY: tidy
+tidy: ## Run go mod tidy across all modules
+	@set -e; for m in $(MODULES); do \
+		echo "==> tidy $$m"; \
+		( cd $$m && go mod tidy ); \
+	done
+
+.PHONY: install-tools
+install-tools: ## Install golangci-lint at the pinned version
+	go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@$(GOLANGCI_LINT_VERSION)
+
+.PHONY: help
+help: ## Show this help
+	@grep -hE '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
+		awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-14s\033[0m %s\n", $$1, $$2}'