Makefile

SHELL := /bin/sh

.DEFAULT_GOAL := help
.DELETE_ON_ERROR:
# Concurrent aggregate runs would distort measurements and multiply disk load.
.NOTPARALLEL: ci bench-report qualify-scheduled

GO ?= go
GOLANGCI_LINT ?= golangci-lint

PACKAGES ?= ./...
ROOT_PACKAGE ?= .
CONSUMER_PACKAGE ?= ./consumer

TEST_ARGS ?=
RACE_ARGS ?=
LOCKRANK_ARGS ?=
VET_ARGS ?=
LINT_ARGS ?=
COVER_PROFILE ?= /tmp/wal-coverage.out

FUZZ_TIME ?= 5s

BENCH_TIME ?= 2s
BENCH_COUNT ?= 5
FIXED_BENCH_COUNT ?= 5
MAINTENANCE_BENCH_COUNT ?= 10
BENCH_ARGS ?=

WAL_SOAK_SEED ?= 155921
WAL_SOAK_STEPS ?= 250000
WAL_QUALIFY ?= 1
WAL_QUALIFY_STREAM_MIB ?= 256
WAL_VOLUME_RECORDS ?= 2000000
WAL_QUALIFY_GIB ?= 1

QUALIFY_MODEL_TIMEOUT ?= 80m
QUALIFY_MILLION_TIMEOUT ?= 50m
QUALIFY_STREAM_TIMEOUT ?= 10m
QUALIFY_BLOB_TIMEOUT ?= 15m
QUALIFY_VOLUME_TIMEOUT ?= 50m
QUALIFY_RETAINED_TIMEOUT ?= 3h
QUALIFY_CRASH_TIMEOUT ?= 25m
QUALIFY_CRASH_COUNT ?= 100

CRASH_TEST_PATTERN := ^TestFileWALSubprocess(RepairsTornAppend|SyncedReceiptSurvivesExit|RecoversRotationCrashPoints|RecoversTransactionCrashPoints|RepeatsInterruptedTransactionCleanup|RecoversTruncateCrashPoints|RecoveryRepairIsCrashIdempotent|RecoversCompactionCrashPoints|RecoversBlobCrashPoints|ResumesBlobRecoveryCleanup)$$

.PHONY: help
help: ## Show the supported development, benchmark, and qualification targets.
	@awk 'BEGIN {FS = ":.*## "; print "Usage: make <target> [VARIABLE=value]\n"} /^[a-zA-Z0-9_.-]+:.*## / {printf "  %-28s %s\n", $$1, $$2}' $(MAKEFILE_LIST)

# Development gates.

.PHONY: fmt
fmt: ## Format all Go source files.
	@find . -type f -name '*.go' -not -path './.git/*' -exec gofmt -w {} +

.PHONY: fmt-check
fmt-check: ## Fail when a Go source file is not gofmt-formatted.
	@unformatted="$$(find . -type f -name '*.go' -not -path './.git/*' -exec gofmt -l {} +)"; \
	if [ -n "$$unformatted" ]; then \
		echo "gofmt required for:"; \
		printf '%s\n' "$$unformatted"; \
		exit 1; \
	fi

.PHONY: vet
vet: ## Run go vet for every package.
	$(GO) vet $(VET_ARGS) $(PACKAGES)

.PHONY: lint
lint: ## Run the configured golangci-lint suite.
	$(GOLANGCI_LINT) run $(LINT_ARGS) $(PACKAGES)

.PHONY: test
test: ## Run the ordinary package tests.
	$(GO) test $(TEST_ARGS) $(PACKAGES)

.PHONY: test-race
test-race: ## Run every package test under the race detector.
	$(GO) test -race $(RACE_ARGS) $(PACKAGES)

.PHONY: test-lockrank
test-lockrank: ## Run all tests with dynamic lock-order enforcement.
	$(GO) test -tags=lockrank $(LOCKRANK_ARGS) $(PACKAGES)

.PHONY: test-lockrank-race
test-lockrank-race: ## Combine lock-order enforcement with the race detector.
	$(GO) test -race -tags=lockrank $(LOCKRANK_ARGS) $(PACKAGES)

.PHONY: lock-doc
lock-doc: ## Regenerate the normative CONCURRENCY.md lock-graph table.
	$(GO) run ./internal/lockrank/cmd/lockgraphdoc -path CONCURRENCY.md

.PHONY: lock-check
lock-check: ## Check graph structure, documentation, and ranked-mutex coverage.
	$(GO) test -run '^(TestLockGraphDocumentationIsCurrent|TestProductionMutexesUseLockGraph)$$' $(ROOT_PACKAGE)
	$(GO) test ./internal/lockrank

.PHONY: test-cover
test-cover: ## Write an atomic statement coverage profile and print its summary.
	$(GO) test -covermode=atomic -coverprofile=$(COVER_PROFILE) $(TEST_ARGS) $(PACKAGES)
	$(GO) tool cover -func=$(COVER_PROFILE)

.PHONY: test-crash
test-crash: ## Run the subprocess crash/recovery boundary family once.
	$(GO) test -run '$(CRASH_TEST_PATTERN)' $(TEST_ARGS) $(ROOT_PACKAGE)

.PHONY: fuzz-smoke
fuzz-smoke: ## Run each format and filename fuzzer for FUZZ_TIME.
	$(GO) test -run '^$$' -fuzz '^FuzzWALGroupDecoder$$' -fuzztime=$(FUZZ_TIME) $(ROOT_PACKAGE)
	$(GO) test -run '^$$' -fuzz '^FuzzWALMetadataDecoders$$' -fuzztime=$(FUZZ_TIME) $(ROOT_PACKAGE)
	$(GO) test -run '^$$' -fuzz '^FuzzWALTransactionDecoders$$' -fuzztime=$(FUZZ_TIME) $(ROOT_PACKAGE)
	$(GO) test -run '^$$' -fuzz '^FuzzWALSegmentFilename$$' -fuzztime=$(FUZZ_TIME) $(ROOT_PACKAGE)
	$(GO) test -run '^$$' -fuzz '^FuzzWALObjectFilename$$' -fuzztime=$(FUZZ_TIME) $(ROOT_PACKAGE)

.PHONY: diff-check
diff-check: ## Check the worktree diff for whitespace errors.
	git diff --check

.PHONY: check
check: fmt-check vet lint test diff-check ## Run the normal local pre-commit gates.

.PHONY: ci
ci: fmt-check vet lint test-race test-lockrank fuzz-smoke diff-check ## Run the complete ordinary CI gate locally.

# Reproducible benchmark profiles from BENCHMARK.md.

.PHONY: bench-small
bench-small: ## Measure small and concurrent producer paths.
	$(GO) test -run '^$$' \
		-bench '^(BenchmarkFileWALAppend(Written4KiB|Synced4KiB|BatchWritten128x1KiB|WrittenConcurrent32|SyncedConcurrent32)|BenchmarkMemoryWAL(AppendVolatile4KiB|Flush|Scan10000))$$' \
		-benchmem -benchtime=$(BENCH_TIME) -count=$(BENCH_COUNT) $(BENCH_ARGS) $(ROOT_PACKAGE)

.PHONY: bench-streaming
bench-streaming: ## Measure reader-backed append, deduplication, and mixed batches.
	$(GO) test -run '^$$' \
		-bench '^(BenchmarkFileWALConcurrentAppendFrom(Written|Synced)|BenchmarkFileWALAppendFromDeduplicatedBlobWritten|BenchmarkFileWALAppendBatchFromMixedWritten)$$' \
		-benchmem -benchtime=$(BENCH_TIME) -count=$(BENCH_COUNT) $(BENCH_ARGS) $(ROOT_PACKAGE)

.PHONY: bench-producer-drain
bench-producer-drain: ## Measure producer throughput with and without durable drain.
	$(GO) test -run '^$$' \
		-bench '^BenchmarkFileWALProducerConcurrent32(Written|Synced)(NoDrain|WithConsumerDrainBatch512)10000x4KiB$$' \
		-benchmem -benchtime=1x -count=$(FIXED_BENCH_COUNT) $(BENCH_ARGS) $(ROOT_PACKAGE)

.PHONY: bench-large
bench-large: ## Measure large records and object-heavy recovery.
	$(GO) test -run '^$$' \
		-bench '^(BenchmarkFileWALAppendBatchFromLargeWritten|BenchmarkFileWALAppendFromDefaultBoundaries64MiB|BenchmarkFileWALScanReaderDefaultBoundaries64MiB|BenchmarkFileWALRecoverLargeStreamingRecord|BenchmarkFileWALRecoverBlobObjects256|BenchmarkFileWALRecoverStagingOrphans256)$$' \
		-benchmem -benchtime=1x -count=$(FIXED_BENCH_COUNT) $(BENCH_ARGS) $(ROOT_PACKAGE)

.PHONY: bench-consumer
bench-consumer: ## Measure out-of-order consumer and direct-reader paths.
	$(GO) test -run '^$$' -bench '^Benchmark(Receiver|Baseline)' \
		-benchmem -benchtime=1x -count=$(FIXED_BENCH_COUNT) $(BENCH_ARGS) $(CONSUMER_PACKAGE)

.PHONY: bench-maintenance
bench-maintenance: ## Measure scan, recovery, degraded open, truncate, and compact.
	$(GO) test -run '^$$' \
		-bench '^Benchmark(FileWALScan10000|FileWALRecover10000|OpenDegradedFileWAL10000|FileWALTruncate10000|FileWALCompact10000)$$' \
		-benchmem -benchtime=1x -count=$(MAINTENANCE_BENCH_COUNT) $(BENCH_ARGS) $(ROOT_PACKAGE)

.PHONY: bench-qualification
bench-qualification: ## Repeat the broader recovery and decoder qualification profile.
	$(GO) test -run '^$$' \
		-bench '^Benchmark(FileWALScan10000|FileWALScanValidate10000|FileWALScanDecode10000|FileWALRecover10000|OpenDegradedFileWAL10000|FileWALTruncate10000|FileWALCompact10000)$$' \
		-benchmem -benchtime=1x -count=$(MAINTENANCE_BENCH_COUNT) $(BENCH_ARGS) $(ROOT_PACKAGE)

.PHONY: bench-report
bench-report: bench-small bench-streaming bench-producer-drain bench-large bench-consumer bench-maintenance ## Reproduce every BENCHMARK.md result group.

.PHONY: bench-all
bench-all: ## Run every benchmark once with Go's default calibration.
	$(GO) test -run '^$$' -bench . -benchmem $(BENCH_ARGS) $(PACKAGES)

# Long-running, opt-in qualification gates.

.PHONY: qualify-reference
qualify-reference: ## Run the seeded reference-model soak.
	WAL_SOAK_SEED=$(WAL_SOAK_SEED) WAL_SOAK_STEPS=$(WAL_SOAK_STEPS) \
		$(GO) test -v -timeout=$(QUALIFY_MODEL_TIMEOUT) -run '^TestFileWALSeededReferenceSoak$$' $(ROOT_PACKAGE)

.PHONY: qualify-million
qualify-million: ## Run the million-record resource gate.
	WAL_QUALIFY=$(WAL_QUALIFY) \
		$(GO) test -v -timeout=$(QUALIFY_MILLION_TIMEOUT) -run '^TestFileWALQualificationMillionRecords$$' $(ROOT_PACKAGE)

.PHONY: qualify-streaming
qualify-streaming: ## Run the bounded streaming heap gate.
	WAL_QUALIFY_STREAM_MIB=$(WAL_QUALIFY_STREAM_MIB) \
		$(GO) test -v -timeout=$(QUALIFY_STREAM_TIMEOUT) -run '^TestFileWALQualificationStreamingHeap$$' $(ROOT_PACKAGE)

.PHONY: qualify-blob-inventory
qualify-blob-inventory: ## Run the object-inventory recovery resource gate.
	WAL_QUALIFY=$(WAL_QUALIFY) \
		$(GO) test -v -timeout=$(QUALIFY_BLOB_TIMEOUT) -run '^TestFileWALQualificationBlobInventory$$' $(ROOT_PACKAGE)

.PHONY: qualify-volume
qualify-volume: ## Run the configurable volume soak.
	WAL_VOLUME_RECORDS=$(WAL_VOLUME_RECORDS) \
		$(GO) test -v -timeout=$(QUALIFY_VOLUME_TIMEOUT) -run '^TestFileWALVolumeSoak$$' $(ROOT_PACKAGE)

.PHONY: qualify-retained
qualify-retained: ## Run the retained-data gate; WAL_QUALIFY_GIB defaults to 1.
	WAL_QUALIFY_GIB=$(WAL_QUALIFY_GIB) \
		$(GO) test -v -timeout=$(QUALIFY_RETAINED_TIMEOUT) -run '^TestFileWALQualificationRetainedGiB$$' $(ROOT_PACKAGE)

.PHONY: qualify-crash
qualify-crash: ## Repeat the subprocess crash family QUALIFY_CRASH_COUNT times.
	$(GO) test -timeout=$(QUALIFY_CRASH_TIMEOUT) -count=$(QUALIFY_CRASH_COUNT) \
		-run '$(CRASH_TEST_PATTERN)' $(ROOT_PACKAGE)

.PHONY: qualify-scheduled
qualify-scheduled: qualify-reference qualify-million qualify-streaming qualify-blob-inventory qualify-volume qualify-crash ## Run the scheduled qualification set; this can take hours.