Makefile

.PHONY: help setup toolchains test-toolchains coverage mutants miri install build dev test \
	nextest perft deps docs links modules typos emdash rustdoc bench fmt fmt-check clippy clean \
	clean-cache watch play search-bench profile lint pre-commit ci info

# Build for the CPU of this machine. CI sets NATIVE_FLAGS to empty, because a cached
# native binary can fail on a runner with a different CPU.
NATIVE_FLAGS := RUSTFLAGS="-C target-cpu=native"

# Cargo tools that `make setup` installs.
CARGO_TOOLS := samply cargo-nextest cargo-machete cargo-deny typos-cli@1.50.3 taplo-cli@0.10.0 \
	lychee@0.24.2 cargo-llvm-cov cargo-mutants

# Pinned nightly toolchain. rustfmt needs it to group and merge imports.
NIGHTLY := nightly-2026-10-01
# Nightly-only rustfmt options. The Makefile passes them here, not in rustfmt.toml, so
# that stable rustfmt (for example in an editor) does not warn about them.
RUSTFMT_NIGHTLY_OPTIONS := --config group_imports=StdExternalCrate,imports_granularity=Module,wrap_comments=true,comment_width=100

# Markdown files that the docs checks cover.
DOCS := README.md CONTRIBUTING.md CLAUDE.md

# Expected perft result at depth 5. Use it to check that move generation is correct.
PERFT_DEPTH_5 := 129421093

.DEFAULT_GOAL := install

setup: toolchains test-toolchains ## Install the toolchains, the cargo tools, and the git hook
	@if command -v cargo-binstall >/dev/null 2>&1; then \
		cargo binstall --no-confirm --locked --disable-strategies quick-install $(CARGO_TOOLS); \
	else \
		cargo install --locked $(CARGO_TOOLS); \
	fi
	git config core.hooksPath .githooks

toolchains: ## Install the stable toolchain from rust-toolchain.toml and the pinned nightly
	rustup toolchain install
	rustup toolchain install $(NIGHTLY) --profile minimal --component rustfmt

test-toolchains: toolchains ## Install the toolchain parts for coverage (llvm-tools) and Miri
	rustup component add llvm-tools-preview
	rustup component add miri rust-src --toolchain $(NIGHTLY)

install: ## Build with native CPU optimizations and install to ~/.cargo/bin
	$(NATIVE_FLAGS) cargo install --path . --locked
	@which chess

build: ## Build release with native CPU optimizations (no install)
	$(NATIVE_FLAGS) cargo build --release

dev: ## Build development version
	cargo build

test: ## Run all tests in the workspace
	cargo test --workspace

nextest: ## Run all tests with cargo-nextest (does not run doc tests)
	cargo nextest run --workspace

perft: ## Check the perft count at depth 5
	@$(NATIVE_FLAGS) cargo run --release --quiet -- dev perft --depth 5 | tail -n 1 \
		| grep "total positions: $(PERFT_DEPTH_5)," \
		|| (echo "perft failed: expected $(PERFT_DEPTH_5) positions at depth 5 (build error, panic, or wrong count)" >&2; exit 1)

deps: ## Check for unused dependencies, advisories, licenses, and sources
	cargo machete
	cargo deny check

rustdoc: ## Build the API docs and fail on rustdoc warnings
	@# The binary has the same name as the library, so cargo doc skips it. Check it first. Cargo
	@# warns that both write the same index.html. The second command writes the library docs.
	cargo rustdoc --bin chess --all-features -- -D warnings --document-private-items
	RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps --document-private-items --all-features

coverage: ## Measure test coverage. Writes an HTML report to target/llvm-cov/html
	cargo llvm-cov --workspace --html
	@cargo llvm-cov report --summary-only | sed -n '1p;$$p'

mutants: ## Mutation tests on tracked changes since main, or on one file with FILE=path (slow)
	@if [ -n "$(FILE)" ]; then \
		cargo mutants --workspace --file $(FILE); \
	else \
		mkdir -p target && git diff $$(git merge-base main HEAD) > target/mutants.diff \
			&& cargo mutants --workspace --in-diff target/mutants.diff; \
	fi

miri: ## Run the concurrent transposition table test under Miri. It fails now (known data race)
	cargo +$(NIGHTLY) miri test --lib -- \
		alpha_beta_searcher::tests::test_tt_concurrent_store_and_probe --exact

docs: ## Lint the Markdown docs: structure, prose (Vale), and local links (needs Node.js 22 and Vale)
	@# package-lock.json pins markdownlint-cli2 and all of its dependencies.
	npm ci --silent --ignore-scripts --no-audit --no-fund
	npx --no-install markdownlint-cli2 $(DOCS)
	vale $(DOCS)
	lychee --offline --no-progress $(DOCS)

links: ## Check all links in the docs, including external links (needs network)
	lychee --no-progress $(DOCS)

bench: ## Run benchmarks
	cargo bench

fmt: ## Format Rust code in all packages (with nightly import grouping) and TOML files
	cargo +$(NIGHTLY) fmt --all -- $(RUSTFMT_NIGHTLY_OPTIONS)
	RUST_LOG=warn taplo fmt

fmt-check: ## Check the format of Rust code and TOML files
	cargo +$(NIGHTLY) fmt --all -- --check $(RUSTFMT_NIGHTLY_OPTIONS)
	RUST_LOG=warn taplo fmt --check

clippy: ## Run clippy on the workspace, with default features and with all features
	cargo clippy --workspace --lib --bins --tests -- -D warnings
	cargo clippy --workspace --all-features --lib --bins --tests -- -D warnings

typos: ## Check spelling in code and docs
	typos

emdash: ## Fail if any tracked text file contains an em dash (U+2014)
	@if git grep -nIF "$$(printf '\342\200\224')"; then \
		echo "Do not use em dashes. Use a colon, a comma, or two hyphens." >&2; exit 1; \
	fi

modules: ## Check for orphan source files, and for a module doc in each source file
	./scripts/check-orphans.sh
	./scripts/check-module-docs.sh

lint: fmt-check clippy typos emdash modules ## Run format checks, clippy, spelling, em dash, orphan, and module doc checks

clean: ## Clean build artifacts
	cargo clean

clean-cache: ## Clear precompiled caches (opening book, zobrist, magic tables)
	@echo "Clearing build cache to force regeneration of precompiled tables..."
	cargo clean
	@echo "Cache cleared. Next build will regenerate all tables."

watch: install ## Watch engine play itself
	chess watch --depth 4

play: install ## Play against engine
	chess play --color white --depth 4

search-bench: install ## Run the alpha-beta search benchmark
	chess dev search-bench --depth 4

profile: build ## Profile perft at depth 6 with samply (opens the Firefox Profiler)
	samply record ./target/release/chess dev perft --depth 6

pre-commit: lint test ## Run pre-commit checks

ci: lint rustdoc docs deps test perft ## Run CI checks

info: ## Show installed binary info
	@which chess
	@du -h $$(which chess)

help: ## Show this help
	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-20s\033[0m %s\n", $$1, $$2}'