refactor, linter, Makefile, benchmarks, and some formatting

.gitignore

@@ -28,5 +28,6 @@ go.work.sum
 .env
 
 # Editor/IDE
-# .idea/
-# .vscode/
+.idea/
+.vscode/
+

.golangci.yml

@@ -0,0 +1,125 @@
+formatters:
+  exclusions:
+    generated: lax
+    paths:
+      - third_party$
+      - builtin$
+      - examples$
+  settings:
+    gofumpt:
+      extra-rules: true
+issues:
+  max-issues-per-linter: 0
+  max-same-issues: 0
+linters:
+  enable:
+    - gomodguard_v2
+  default: all
+  disable:
+    # -- temporary disabled todo: enable later --
+    - noinlineerr
+    - errcheck
+    - noctx
+    - nonamedreturns
+    - unparam
+    - govet
+    - forcetypeassert
+    - gosec
+    # -- temporary disabled --
+    - thelper
+    - goconst
+    - gomodguard
+    - cyclop
+    - depguard
+    - dupword
+    - exhaustruct
+    - funlen
+    - gochecknoglobals
+    - gocognit
+    - gocyclo
+    - godox
+    - lll
+    - mnd
+    - nestif
+    - rowserrcheck
+    - varnamelen
+    - wsl
+    - wrapcheck
+    - revive
+    - err113
+    - dupl
+    - paralleltest
+    - nolintlint
+    - godot
+    - interfacebloat
+    - ireturn
+    - containedctx
+    - testpackage
+    - tagalign
+  exclusions:
+    generated: lax
+    paths:
+      - third_party$
+      - builtin$
+      - examples$
+    presets:
+      - common-false-positives
+      - legacy
+  settings:
+    revive:
+      confidence: 0.8
+      rules:
+        - name: exported
+          arguments: [ ]
+        - name: var-naming
+          arguments:
+            - ID
+            - [ ]
+        - name: package-comments
+        - name: dot-imports
+        - name: blank-imports
+        - name: context-as-argument
+        - name: context-keys-type
+        - name: error-return
+        - name: error-strings
+        - name: error-naming
+        - name: increment-decrement
+        - name: indent-error-flow
+        - name: receiver-naming
+        - name: range
+        - name: time-naming
+        - name: unexported-return
+        - name: errorf
+        - name: empty-block
+        - name: superfluous-else
+        - name: unreachable-code
+        - name: redefines-builtin-id
+        - name: if-return
+    errcheck:
+      check-blank: true
+      check-type-assertions: true
+    wrapcheck:
+      ignore-sigs:
+        - ".Errorf("
+        - errors.New(
+        - errors.Unwrap(
+        - errors.Join(
+        - ".Wrap("
+        - ".Wrapf("
+        - ".WithMessage("
+        - ".WithMessagef("
+        - ".WithStack("
+    err113:
+      check-type-assertion: true
+    misspell:
+      locale: US
+    govet:
+      enable:
+        - shadow
+    dupl:
+      threshold: 150
+run:
+  concurrency: 4
+  issues-exit-code: 1
+  tests: true
+version: 2

.tool-versions

@@ -0,0 +1,2 @@
+golang 1.26.5
+golangci-lint 2.12.2

Makefile

@@ -0,0 +1,50 @@
+BINARY := ktls
+BUILD_DIR := bin
+COVERAGE_FILE := coverage.out
+COVERAGE_HTML := coverage.html
+
+.DEFAULT_GOAL := help
+
+.PHONY: help build test test-integration cover lint lint-fix fmt vet tidy update bench clean tools
+
+help: ## Show this help.
+	@grep -E '^[a-zA-Z0-9_.-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
+		awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-22s\033[0m %s\n", $$1, $$2}'
+
+build: ## Compile the library and any commands.
+	@mkdir -p $(BUILD_DIR)
+	go build ./...
+
+test: ## Run unit tests with race detection, shuffle, timeout, and coverage.
+	go clean -testcache && \
+    CGO_ENABLED=1 go test -race -shuffle=on -timeout=2m -covermode=atomic -coverprofile=$(COVERAGE_FILE) ./...
+
+test-integration: ## Run integration tests selected by the integration build tag.
+	go clean -testcache && \
+	CGO_ENABLED=1 go test -race -shuffle=on -timeout=5m -tags=integration ./...
+
+cover: test ## Render the unit-test coverage report as HTML.
+	go tool cover -html=$(COVERAGE_FILE) -o $(COVERAGE_HTML)
+	@printf 'Coverage report written to %s\n' $(COVERAGE_HTML)
+
+lint: ## Run the required static-analysis suite.
+	golangci-lint run ./...
+
+lint-fix: ## Apply safe formatter and linter fixes, then report remaining findings.
+	golangci-lint run --fix ./...
+
+tidy: ## Normalize module metadata and verify every dependency.
+	go mod tidy
+	go mod verify
+
+update: ## Upgrade all dependencies to their latest minor/patch versions.
+	go get -u ./...
+	go mod tidy
+	go mod verify
+
+bench: ## Run all benchmarks with memory allocation statistics.
+	go clean -testcache
+	CGO_ENABLED=0 go test -run='^$$' -bench=. -benchmem ./...
+
+clean: ## Remove locally generated build and coverage artifacts.
+	rm -rf $(BUILD_DIR) $(COVERAGE_FILE) $(COVERAGE_HTML)