Makefile

.PHONY: help setup-dev format lint typecheck test test-db test-db-local test-db-local-clean test-db-local-down test-all check docs docs-gettext docs-translate docs-lang docs-verify ci ci-backend ci-database ci-frontend clean

.DEFAULT_GOAL := help

# Allow overriding uv run flags, e.g.:
#   make lint UV_RUN="uv run --active"
UV_RUN ?= uv run
PYTHON_VERSION ?= 3.12
# Match CI's execution mode; use PYTEST_WORKERS=0 for a serial debugging run.
PYTEST_WORKERS ?= 4

RESET := \033[0m
BOLD := \033[1m
GREEN := \033[32m
YELLOW := \033[33m
BLUE := \033[34m

help:  ## Show this help message
	@echo "$(BOLD)Available targets:$(RESET)"
	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  $(BLUE)%-12s$(RESET) %s\n", $$1, $$2}'

setup-dev:  ## Create the virtualenv and install dependencies
	uv venv -p $(PYTHON_VERSION)
	uv sync
	@echo "$(GREEN)OK Dev environment ready (activate with: source .venv/bin/activate)$(RESET)"

format:  ## Format code with ruff
	@echo "$(YELLOW)Running formatter...$(RESET)"
	$(UV_RUN) ruff format .
	$(UV_RUN) ruff check --fix .
	@echo "$(GREEN)OK Code formatted$(RESET)"

lint:  ## Run linters (ruff format check, ruff lint)
	@echo "$(YELLOW)Running linters...$(RESET)"
	$(UV_RUN) ruff format --check .
	$(UV_RUN) ruff check --no-fix .
	@echo "$(GREEN)OK Linting passed$(RESET)"

typecheck:  ## Type-check all three packages (mypy; config in pyproject.toml)
	@echo "$(YELLOW)Running mypy...$(RESET)"
	$(UV_RUN) mypy
	@echo "$(GREEN)OK Type check passed$(RESET)"

test:  ## Run tests (exclude external and db-dependent)
	@echo "$(YELLOW)Running tests (not external, not dbtest)...$(RESET)"
	$(UV_RUN) pytest -n $(PYTEST_WORKERS) --dist loadfile -q -m "not external and not dbtest"
	@echo "$(GREEN)OK Tests passed$(RESET)"

test-db:  ## Run the dbtest tier (needs Postgres; see TEST_DB_* in ENVIRONMENT.md)
	$(UV_RUN) pytest -vv -m "dbtest"

# ARGS passes pytest arguments through, e.g. ARGS="tests/integration/storage -x".
test-db-local:  ## Run the dbtest tier on this machine's shared test PostgreSQL (needs Docker)
	UV_RUN="$(UV_RUN)" ./scripts/test-db-local.sh run $(ARGS)

test-db-local-clean:  ## Drop local test databases of checkouts that no longer exist
	UV_RUN="$(UV_RUN)" ./scripts/test-db-local.sh clean

# Discards every checkout's databases and fails their runs; never from an agent.
test-db-local-down:  ## Remove the shared local test PostgreSQL container
	./scripts/test-db-local.sh down

test-all:  ## Run all tests except external (includes db-dependent)
	$(UV_RUN) pytest -q -m "not external"

check: format lint typecheck test  ## Format, lint, type-check, and test — the gate every task must pass

# Warnings are errors, and --keep-going reports every one instead of stopping
# at the first. conf.py builds each translation into docs/build/html/<code>/
# from this one invocation, so this produces the whole published tree;
# DOCS_LANGUAGES="en:English" builds English alone. CI's Docs Build job runs
# docs-verify, which starts with this target.
docs:  ## Build the developer documentation (every language) into docs/build/html
	$(UV_RUN) sphinx-build -b html -W --keep-going docs/developer docs/build/html
	@echo "$(GREEN)OK Docs built: docs/build/html/index.html$(RESET)"

DOCS_LANG ?= zh_CN

docs-gettext:  ## Extract translatable strings from the docs into docs/gettext/
	$(UV_RUN) sphinx-build -b gettext -q docs/developer docs/gettext
	@echo "$(GREEN)OK Catalog templates: docs/gettext/$(RESET)"

# uvx rather than a pinned dev dependency: only translators run this.
docs-translate: docs-gettext  ## Create or update the catalogs for DOCS_LANG (default zh_CN)
	uvx sphinx-intl update -p docs/gettext -d docs/developer/locale -l $(DOCS_LANG)
	@echo "$(GREEN)OK Edit docs/developer/locale/$(DOCS_LANG)/LC_MESSAGES/*.po$(RESET)"

docs-lang:  ## Build one translated language into docs/build/html-$(DOCS_LANG)
	$(UV_RUN) sphinx-build -b html -W --keep-going -D language=$(DOCS_LANG) \
		docs/developer docs/build/html-$(DOCS_LANG)
	@echo "$(GREEN)OK Docs built: docs/build/html-$(DOCS_LANG)/index.html$(RESET)"

# A translation never fails loudly: Sphinx falls back to English for any string
# it cannot translate, so a stale catalog builds clean under -W and reads as
# English. The checker is what notices.
docs-verify: docs docs-gettext  ## Build the site and check every translation still applies
	$(UV_RUN) python scripts/check_docs_translations.py docs/build/html docs/developer/locale \
		--gettext-dir docs/gettext

ci:  ## Run all local CI tiers (check-only; needs uv, Python 3.12, Node 22, and Docker)
	./scripts/ci-local.sh

ci-backend:  ## Run local backend CI (lint, mypy, and non-external/non-db tests)
	./scripts/ci-local.sh backend

ci-database:  ## Run local database CI against disposable PostgreSQL 15
	./scripts/ci-local.sh database

ci-frontend:  ## Run local frontend CI (lint, format check, types, tests, and build guards)
	./scripts/ci-local.sh frontend

clean:  ## Remove caches and build artifacts
	rm -rf .pytest_cache .ruff_cache .mypy_cache .coverage coverage.xml htmlcov build dist *.egg-info apps/backend/*.egg-info docs/build docs/gettext
	find . -type d \( -name .venv -o -name venv -o -name node_modules \) -prune -o -type d -name __pycache__ -exec rm -rf {} +